ably 0.1.1 → 0.1.2

data/lib/ably/realtime/connection.rb

@@ -4,12 +4,16 @@ module Ably
       include Callbacks
 
       def initialize(client)
-        @client = client
+        @client         = client
+        @message_serial = 0
       end
 
-      # Ably::Realtime interface
-      def send(data)
-        @driver.text(data)
+      def send(protocol_message)
+        add_message_serial_if_ack_required_to(protocol_message) do
+          protocol_message = Models::ProtocolMessage.new(protocol_message)
+          client.log_http("Prot msg sent =>: #{protocol_message.action_sym} #{protocol_message.to_json}")
+          driver.text(protocol_message.to_json)
+        end
       end
 
       # EventMachine::Connection interface
@@ -22,12 +26,12 @@ module Ably
       def connection_completed
         trigger :connecting
 
-        start_tls if @client.use_tls?
-        @driver.start
+        start_tls if client.use_tls?
+        driver.start
       end
 
       def receive_data(data)
-        @driver.parse(data)
+        driver.parse(data)
       end
 
       def unbind
@@ -36,7 +40,9 @@ module Ably
 
       # WebSocket::Driver interface
       def url
-        @client.endpoint.to_s
+        URI(client.endpoint).tap do |endpoint|
+          endpoint.query = URI.encode_www_form(client.auth.auth_params.merge(timestamp: Time.now.to_i, binary: false))
+        end.to_s
       end
 
       def write(data)
@@ -44,16 +50,37 @@ module Ably
       end
 
       private
+      attr_reader :client, :driver, :message_serial
+
+      def add_message_serial_if_ack_required_to(data)
+        if Models::ProtocolMessage.ack_required?(data[:action])
+          add_message_serial_to(data) { yield }
+        else
+          yield
+        end
+      end
+
+      def add_message_serial_to(data)
+        @message_serial += 1
+        data.merge!(msg_serial: @message_serial)
+        yield
+      rescue StandardError => e
+        @message_serial -= 1
+        raise e
+      end
+
       def setup_driver
         @driver = WebSocket::Driver.client(self)
 
-        @driver.on("open")  { trigger :connected }
-
-        @driver.on("message") do |event|
-          message = JSON.parse(event.data, symbolize_names: true)
-          action  = ACTIONS.detect { |k,v| v == message[:action] }.first
+        driver.on("open") do
+          client.log_http("WebSocket connection opened to #{url}")
+          trigger :connected
+        end
 
-          @client.trigger action, message
+        driver.on("message") do |event|
+          message = Models::ProtocolMessage.new(JSON.parse(event.data))
+          client.log_http("Prot msg recv <=: #{message.action_sym} #{message.to_json}")
+          client.trigger message.action_sym, message
         end
       end
     end

data/lib/ably/realtime/models/error_info.rb

@@ -0,0 +1,38 @@
+module Ably::Realtime::Models
+  # An exception type encapsulating error information containing
+  # an Ably-specific error code and generic status code.
+  #
+  # @!attribute [r] message
+  #   @return [String] Additional reason information, where available
+  # @!attribute [r] code
+  #   @return [Integer] Ably error code (see ably-common/protocol/errors.json)
+  # @!attribute [r] status
+  #   @return [Integer] HTTP Status Code corresponding to this error, where applicable
+  # @!attribute [r] json
+  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
+  #
+  class ErrorInfo
+    include Shared
+    include Ably::Modules::Conversions
+
+    def initialize(json_object)
+      @raw_json_object = json_object
+      @json_object     = rubify(@raw_json_object).freeze
+    end
+
+    %w( message code status ).each do |attribute|
+      define_method attribute do
+        json[attribute.to_sym]
+      end
+    end
+
+    def json
+      @json_object
+    end
+    alias_method :to_json, :json
+
+    def to_s
+      "Error: #{message} (code: #{code}, status: #{status})"
+    end
+  end
+end

data/lib/ably/realtime/models/message.rb

@@ -0,0 +1,85 @@
+module Ably::Realtime::Models
+  # A class representing an individual message to be sent or received
+  # via the Ably Realtime service.
+  #
+  # @!attribute [r] name
+  #   @return [String] The event name, if available
+  # @!attribute [r] client_id
+  #   @return [String] The id of the publisher of this message
+  # @!attribute [r] data
+  #   @return [Object] The message payload. See the documentation for supported datatypes.
+  # @!attribute [r] sender_timestamp
+  #   @return [Time] Timestamp when the message was sent according to the publisher client
+  # @!attribute [r] ably_timestamp
+  #   @return [Time] Timestamp when the message was received by the Ably the service for publishing
+  # @!attribute [r] message_id
+  #   @return [String] A globally unique message ID
+  # @!attribute [r] json
+  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
+  #
+  class Message
+    include Shared
+    include Ably::Modules::Conversions
+
+    def initialize(json_object, protocol_message)
+      @protocol_message = protocol_message
+      @raw_json_object  = json_object
+      @json_object      = rubify(@raw_json_object, ignore: [:data]).freeze
+    end
+
+    %w( name client_id ).each do |attribute|
+      define_method attribute do
+        json[attribute.to_sym]
+      end
+    end
+
+    def data
+      @data ||= json[:data].freeze
+    end
+
+    def message_id
+      "#{connection_id}:#{message_serial}:#{protocol_message_index}"
+    end
+
+    def sender_timestamp
+      Time.at(json[:timestamp] / 1000.0) if json[:timestamp]
+    end
+
+    def ably_timestamp
+      protocol_message.timestamp
+    end
+
+    def json
+      @json_object
+    end
+
+    def to_json_object
+      raise RuntimeError, ":name is missing, cannot generate valid JSON for Message" unless name
+
+      json_object = json.dup.tap do |json_object|
+        json_object[:timestamp] = Time.now.to_i * 1000 unless sender_timestamp
+      end
+
+      javify(json_object)
+    end
+
+    def to_json
+      to_json_object.to_json
+    end
+
+    private
+    attr_reader :protocol_message
+
+    def protocol_message_index
+      protocol_message.messages.index(self)
+    end
+
+    def connection_id
+      protocol_message.connection_id
+    end
+
+    def message_serial
+      protocol_message.message_serial
+    end
+  end
+end

data/lib/ably/realtime/models/protocol_message.rb

@@ -0,0 +1,149 @@
+module Ably::Realtime::Models
+  # A message sent and received over the Realtime protocol.
+  # A ProtocolMessage always relates to a single channel only, but
+  # can contain multiple individual Messages or PresenceMessages.
+  # ProtocolMessages are serially numbered on a connection.
+  # See the {http://docs.ably.io/client-lib-development-guide/protocol/ Ably client library developer documentation}
+  # for further details on the members of a ProtocolMessage
+  #
+  # @!attribute [r] action
+  #   @return [Integer] Protocol Message action from list of {ACTIONS}
+  # @!attribute [r] action_sym
+  #   @return [Symbol] Protocol Message action as a symbol
+  # @!attribute [r] count
+  #   @return [Integer] The count field is used for ACK and NACK actions. See {http://docs.ably.io/client-lib-development-guide/protocol/#message-acknowledgement message acknowledgement protocol}
+  # @!attribute [r] error_info
+  #   @return [ErrorInfo] Contains error information
+  # @!attribute [r] channel
+  #   @return [String] Channel name for messages
+  # @!attribute [r] channel_serial
+  #   @return [String] Contains a serial number for amessage on the current channel
+  # @!attribute [r] connection_id
+  #   @return [String] Contains a string connection ID
+  # @!attribute [r] connection_serial
+  #   @return [Bignum] Contains a serial number for a message on the current connection
+  # @!attribute [r] message_serial
+  #   @return [Bignum] Contains a serial number for a message sent from the client to the service.
+  # @!attribute [r] timestamp
+  #   @return [Time] An optional timestamp, applied by the service in messages sent to the client, to indicate the system time at which the message was sent (milliseconds past epoch)
+  # @!attribute [r] messages
+  #   @return [Message] A {ProtocolMessage} with a `:message` action contains one or more messages belonging to a channel.
+  # @!attribute [r] presence
+  #   @return [PresenceMessage] A {ProtocolMessage} with a `:presence` action contains one or more presence updates belonging to a channel.
+  # @!attribute [r] json
+  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
+  #
+  class ProtocolMessage
+    include Shared
+    include Ably::Modules::Conversions
+
+    # Actions which are sent by the Ably Realtime API
+    #
+    # The values correspond to the ints which the API
+    # understands.
+    ACTIONS = {
+      heartbeat:    0,
+      ack:          1,
+      nack:         2,
+      connect:      3,
+      connected:    4,
+      disconnect:   5,
+      disconnected: 6,
+      close:        7,
+      closed:       8,
+      error:        9,
+      attach:       10,
+      attached:     11,
+      detach:       12,
+      detached:     13,
+      presence:     14,
+      message:      15
+    }.freeze
+
+    # Retrieve an action symbol by the integer value
+    def self.action_sym_for(action_int)
+      @actions_index_by_int ||= ACTIONS.invert.freeze
+      @actions_index_by_int[action_int]
+    end
+
+    # Retrive an action integer value from a symbol and raise an exception if invalid
+    def self.action!(action_sym)
+      ACTIONS.fetch(action_sym)
+    end
+
+    # Indicates this protocol message action will generate an ACK response such as :message or :presence
+    def self.ack_required?(for_action)
+      for_action = ACTIONS.fetch(for_action) if for_action.kind_of?(Symbol)
+      [action!(:presence), action!(:message)].include?(for_action)
+    end
+
+    def initialize(json_object)
+      @raw_json_object = json_object
+      @json_object     = rubify(@raw_json_object).freeze
+    end
+
+    %w( action count
+        channel channel_serial
+        connection_id connection_serial ).each do |attribute|
+      define_method attribute do
+        json[attribute.to_sym]
+      end
+    end
+
+    def action_sym
+      self.class.action_sym_for(action)
+    end
+
+    def error
+      @error_info ||= ErrorInfo.new(json[:error]) if json[:error]
+    end
+
+    def timestamp
+      Time.at(json[:timestamp] / 1000.0) if json[:timestamp]
+    end
+
+    def message_serial
+      json[:msg_serial]
+    end
+
+    def messages
+      @messages ||=
+        Array(json[:messages]).map do |message|
+          Message.new(message, self)
+        end
+    end
+
+    def presence
+      @presence ||=
+        Array(json[:presence]).map do |message|
+          PresenceMessage.new(message, self)
+        end
+    end
+
+    def json
+      @json_object
+    end
+
+    # Indicates this protocol message will generate an ACK response when sent
+    # Examples of protocol messages required ACK include :message and :presence
+    def ack_required?
+      self.class.ack_required?(action)
+    end
+
+    def to_json_object
+      raise RuntimeError, ":action is missing, cannot generate valid JSON for ProtocolMessage" unless action_sym
+      raise RuntimeError, ":msg_serial is missing, cannot generate valid JSON for ProtocolMessage" if ack_required? && !message_serial
+
+      json_object = json.dup.tap do |json_object|
+        json_object[:messages] = messages.map(&:to_json_object) unless messages.empty?
+        json_object[:presence] = presence.map(&:to_json_object) unless presence.empty?
+      end
+
+      javify(json_object)
+    end
+
+    def to_json
+      to_json_object.to_json
+    end
+  end
+end

data/lib/ably/realtime/models/shared.rb

@@ -0,0 +1,17 @@
+module Ably::Realtime::Models
+  module Shared
+    include Ably::Modules::Conversions
+
+    # Provide a normal Hash accessor to the underlying raw message object
+    #
+    # @return [Object]
+    def [](key)
+      json[key]
+    end
+
+    def ==(other)
+      other.kind_of?(self.class) &&
+        json == other.json
+    end
+  end
+end

data/lib/ably/rest.rb

@@ -1,16 +1,29 @@
 require "ably/rest/channel"
 require "ably/rest/channels"
 require "ably/rest/client"
-require "ably/rest/paged_resource"
+require "ably/rest/models/message"
+require "ably/rest/models/paged_resource"
 require "ably/rest/presence"
 
 module Ably
   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)
+    #
+    # @yield (see Ably::Rest::Client#initialize)
+    # @yieldparam (see Ably::Rest::Client#initialize)
+    # @yieldreturn (see Ably::Rest::Client#initialize)
+    #
     # @return [Ably::Rest::Client]
-    def self.new(*args)
-      Ably::Rest::Client.new(*args)
+    #
+    # @example
+    #    # create a new client authenticating with basic auth
+    #    client = Ably::Rest.new('key.id:secret')
+    #
+    def self.new(options, &auth_block)
+      Ably::Rest::Client.new(options, &auth_block)
     end
   end
 end

data/lib/ably/rest/channel.rb

@@ -41,13 +41,13 @@ module Ably
       # @option options [Integer]   :limit      Maximum number of messages to retrieve up to 10,000
       # @option options [Symbol]    :by         `:message`, `:bundle` or `:hour`. Defaults to `:message`
       #
-      # @return [PagedResource] An Array of hashes representing the message history that supports paging (next, first)
+      # @return [Models::PagedResource<Models::Message>] An Array of hashes representing the message history that supports paging (next, first)
       def history(options = {})
         url = "#{base_path}/messages"
         # TODO: Remove live param as all history should be live
         response = client.get(url, options.merge(live: true))
 
-        PagedResource.new(response, url, client, coerce_into: 'Ably::Message')
+        Models::PagedResource.new(response, url, client, coerce_into: 'Ably::Rest::Models::Message')
       end
 
       def presence

data/lib/ably/rest/client.rb

@@ -6,7 +6,7 @@ require "ably/rest/middleware/parse_json"
 
 module Ably
   module Rest
-    # Wrapper for the Ably REST API
+    # Client for the Ably REST API
     #
     # @!attribute [r] auth
     #   @return {Ably::Auth} authentication object configured for this connection
@@ -19,37 +19,26 @@ module Ably
     # @!attribute [r] environment
     #   @return [String] May contain 'sandbox' when testing the client library against an alternate Ably environment
     class Client
-      include Ably::Support
+      include Ably::Modules::HttpHelpers
       extend Forwardable
 
       DOMAIN = "rest.ably.io"
 
       attr_reader :tls, :environment, :auth, :channels
-      def_delegator :auth, :client_id, :auth_options
+      def_delegators :auth, :client_id, :auth_options
 
       # Creates a {Ably::Rest::Client Rest Client} and configures the {Ably::Auth} object for the connection.
       #
       # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key
+      # @option options (see Ably::Auth#authorise)
       # @option options [Boolean] :tls          TLS is used by default, providing a value of false disbles TLS.  Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections.
       # @option options [String]  :api_key      API key comprising the key ID and key secret in a single string
-      # @option options [String]  :key_id       key ID for the designated application (defaults to client key_id)
-      # @option options [String]  :key_secret   key secret for the designated application used to sign token requests (defaults to client key_secret)
-      # @option options [String]  :client_id    client ID identifying this connection to other clients (defaults to client client_id if configured)
-      # @option options [String]  :auth_url     a URL to be used to GET or POST a set of token request params, to obtain a signed token request.
-      # @option options [Hash]    :auth_headers a set of application-specific headers to be added to any request made to the authUrl
-      # @option options [Hash]    :auth_params  a set of application-specific query params to be added to any request made to the authUrl
-      # @option options [Symbol]  :auth_method  HTTP method to use with auth_url, must be either `:get` or `:post` (defaults to :get)
-      # @option options [Integer] :ttl          validity time in seconds for the requested {Ably::Token}.  Limits may apply, see {http://docs.ably.io/other/authentication/}
-      # @option options [Hash]    :capability   canonicalised representation of the resource paths and associated operations
-      # @option options [Boolean] :query_time   when true will query the {https://ably.io Ably} system for the current time instead of using the local time
-      # @option options [Integer] :timestamp    the time of the of the request in seconds since the epoch
-      # @option options [String]  :nonce        an unquoted, unescaped random string of at least 16 characters
       # @option options [String]  :environment  Specify 'sandbox' when testing the client library against an alternate Ably environment
       # @option options [Boolean] :debug_http   Send HTTP debugging information from Faraday for all HTTP requests to STDOUT
       #
-      # @yield [options] (optional) if an auth block is passed to this method, then this block will be called to create a new token request object
-      # @yieldparam [Hash] options options passed to request_token will be in turn sent to the block in this argument
-      # @yieldreturn [Hash] valid token request object, see {#create_token_request}
+      # @yield (see Ably::Auth#authorise)
+      # @yieldparam (see Ably::Auth#authorise)
+      # @yieldreturn (see Ably::Auth#authorise)
       #
       # @return [Ably::Rest::Client]
       #
@@ -77,8 +66,9 @@ module Ably
 
       # Return a REST {Ably::Rest::Channel} for the given name
       #
-      # @param [String] name see {Ably::Rest::Channels#get}
-      # @param [Hash] channel_options see {Ably::Rest::Channels#get}
+      # @param (see Ably::Rest::Channels#get)
+      #
+      # @return (see Ably::Rest::Channels#get)
       def channel(name, channel_options = {})
         channels.get(name, channel_options)
       end
@@ -137,6 +127,13 @@ module Ably
         )
       end
 
+      # When true, will send HTTP debugging information from Faraday for all HTTP requests to STDOUT
+      #
+      # @return [Boolean]
+      def debug_http?
+        !!@debug_http
+      end
+
       private
       def request(method, path, params = {}, options = {})
         reauthorise_on_authorisation_failure do