ably 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b99a13d28dd5bd7e6b1d35e6ad0d718e759fbb3
-  data.tar.gz: fa7e7aac5a7acf5cc74bfc1da6faf48913ef0f36
+  metadata.gz: bc321ac8e501652f72e08617651df2f90118a759
+  data.tar.gz: 9f9b3f5abedeba6a4ac79841a7e1d5d09bf2bc4c
 SHA512:
-  metadata.gz: 8d2771237651cc84bc83f3de5c6e5438f6e04f57b36432d4394995f5ed7deae8e097d397d149a13e23993116d1f1f2266de046e7c1cca42e36ae776a92a6b5b6
-  data.tar.gz: 9f12b4aef062743e6bbfd7b40388dd7582b42d9634efb062a66ea4a181f815d5c44473e97a48b6c9b3c6862bd07d1bcf12e2d366006da5925f20f9c7d1d8a35e
+  metadata.gz: cdd44c54e0015062c3ecd62bb39f2e03e2a5fe39118939bd7bd18d1bbddd3d774cd511634dac8273890d57b2fd2f2a2191df91016090a54e4e9ca8ffed3823c6
+  data.tar.gz: 4ef9786cc786a7d4b6b824bf5bc137b17d92180c0b3d201ba48cb3d6aa9cf85a56fb8b3639170a4d0ce4f41179e1b6780569e8727df761f5a9f384df20f4535c

data/README.md

@@ -55,6 +55,16 @@ channel = client.channel("test")
 channel.publish("greeting", "Hello World!")
 ```
 
+### Presence on a channel
+
+```ruby
+client = Ably::Realtime.new(api_key: "xxxxx")
+channel = client.channel("test")
+channel.presence.enter(client_data: 'john.doe') do |presence|
+  presence.get #=> [Array of members present]
+end
+```
+
 ## Using the REST API
 
 ### Publishing a message to a channel
@@ -78,7 +88,7 @@ channel.history #=> [{:name=>"test", :data=>"payload"}]
 ```ruby
 client = Ably::Rest.new(api_key: "xxxxx")
 client.auth.authorise # creates a token and will use token authentication moving forwards
-client.auth.current_token #=> #<Ably::Token>
+client.auth.current_token #=> #<Ably::Models::Token>
 channel.publish("myEvent", "Hello!") #=> true, sent using token authentication
 ```
 

data/ably.gemspec

@@ -18,11 +18,12 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "eventmachine"
+  spec.add_runtime_dependency "eventmachine", "~> 1.0"
+  spec.add_runtime_dependency "statesman", "~> 1.0.0.beta2"
   spec.add_runtime_dependency "faraday", "~> 0.9"
   spec.add_runtime_dependency "json"
-  spec.add_runtime_dependency "websocket-driver"
-  spec.add_runtime_dependency "msgpack"
+  spec.add_runtime_dependency "websocket-driver", "~> 0.3"
+  spec.add_runtime_dependency "msgpack", "~> 0.5"
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"

data/lib/ably.rb

@@ -1,4 +1,4 @@
-%w(modules models util).each do |namespace|
+%w(modules util).each do |namespace|
   Dir.glob(File.expand_path("ably/#{namespace}/*.rb", File.dirname(__FILE__))).each do |file|
     require file
   end
@@ -8,8 +8,12 @@ require "ably/auth"
 require "ably/exceptions"
 require "ably/realtime"
 require "ably/rest"
-require "ably/token"
 require "ably/version"
 
+# Ably is the base namespace for the Ably {Ably::Realtime Realtime} & {Ably::Rest Rest} client libraries.
+#
+# Please refer to the {file:README.md Readme} on getting started.
+#
+# @see file:README.md README
 module Ably
 end

data/lib/ably/auth.rb

@@ -12,7 +12,7 @@ module Ably
   # @!attribute [r] client_id
   #   @return [String] The provided client ID, used for identifying this client for presence purposes
   # @!attribute [r] current_token
-  #   @return [Ably::Token] Current {Ably::Token} issued by this library or one of the provided callbacks used to authenticate requests
+  #   @return [Ably::Models::Token] Current {Ably::Models::Token} issued by this library or one of the provided callbacks used to authenticate requests
   # @!attribute [r] token_id
   #   @return [String] Token ID provided to the {Ably::Client} constructor that is used to authenticate all requests
   # @!attribute [r] api_key
@@ -37,7 +37,7 @@ module Ably
     # @param [Hash] auth_options          see {Ably::Rest::Client#initialize}
     # @yield [auth_options]               see {Ably::Rest::Client#initialize}
     def initialize(client, auth_options, &auth_block)
-      auth_options = auth_options.clone
+      auth_options = auth_options.dup
 
       @client        = client
       @options       = auth_options
@@ -81,7 +81,7 @@ module Ably
     # @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 [Integer] :ttl          validity time in seconds for the requested {Ably::Models::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 [Time]    :timestamp    the time of the of the request
@@ -90,9 +90,9 @@ module Ably
     #
     # @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}
+    # @yieldreturn [Hash] valid token request object, see {Auth#create_token_request}
     #
-    # @return [Ably::Token]
+    # @return [Ably::Models::Token]
     #
     # @example
     #    # will issue a simple token request using basic auth
@@ -113,7 +113,7 @@ module Ably
       @current_token = request_token(options, &block)
     end
 
-    # Request a {Ably::Token} which can be used to make authenticated token based requests
+    # Request a {Ably::Models::Token} which can be used to make authenticated token based requests
     #
     # @param [Hash] options the options for the token request
     # @option options [String]  :key_id       key ID for the designated application (defaults to client key_id)
@@ -123,7 +123,7 @@ module Ably
     # @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 [Integer] :ttl          validity time in seconds for the requested {Ably::Models::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 [Time]    :timestamp    the time of the of the request
@@ -131,9 +131,9 @@ module Ably
     #
     # @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}
+    # @yieldreturn [Hash] valid token request object, see {Auth#create_token_request}
     #
-    # @return [Ably::Token]
+    # @return [Ably::Models::Token]
     #
     # @example
     #    # simple token request using basic auth
@@ -165,7 +165,7 @@ module Ably
       response = client.post("/keys/#{token_request.fetch(:id)}/requestToken", token_request, send_auth_header: false)
       body = IdiomaticRubyWrapper(response.body)
 
-      Ably::Token.new(body.fetch(:access_token))
+      Ably::Models::Token.new(body.fetch(:access_token))
     end
 
     # Creates and signs a token request that can then subsequently be used by any client to request a token
@@ -174,7 +174,7 @@ module Ably
     # @option options [String]  :key_id     key ID for the designated application
     # @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
-    # @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 [Integer] :ttl        validity time in seconds for the requested {Ably::Models::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 [Time]    :timestamp  the time of the of the request
@@ -210,9 +210,9 @@ module Ably
       token_request = {
         id:         request_key_id,
         client_id:  client_id,
-        ttl:        Token::DEFAULTS[:ttl],
+        ttl:        Ably::Models::Token::DEFAULTS[:ttl],
         timestamp:  timestamp,
-        capability: Token::DEFAULTS[:capability],
+        capability: Ably::Models::Token::DEFAULTS[:capability],
         nonce:      SecureRandom.hex
       }.merge(token_options.select { |key, val| token_attributes.include?(key.to_s) })
 
@@ -354,11 +354,18 @@ module Ably
       connection = Faraday.new("#{uri.scheme}://#{uri.host}", connection_options)
       method = options[:auth_method] || :get
 
-      connection.send(method) do |request|
+      response = connection.send(method) do |request|
         request.url uri.path
         request.params = options[:auth_params] || {}
         request.headers = options[:auth_headers] || {}
-      end.body
+      end
+
+      unless response.body.kind_of?(Hash)
+        raise Ably::Exceptions::InvalidResponseBody,
+              "Content Type #{response.headers['Content-Type']} is not supported by this client library"
+      end
+
+      response.body
     end
 
     # Return a Hash of connection options to initiate the Faraday::Connection with
@@ -383,11 +390,12 @@ module Ably
     # @see http://mislav.uniqpath.com/2011/07/faraday-advanced-http/
     def middleware
       @middleware ||= Faraday::RackBuilder.new do |builder|
-        setup_middleware builder
+        setup_outgoing_middleware builder
 
         # Raise exceptions if response code is invalid
         builder.use Ably::Rest::Middleware::ExternalExceptions
 
+        setup_incoming_middleware builder
 
         # Log HTTP requests if log level is DEBUG option set
         builder.response :logger if client.log_level == Logger::DEBUG

data/lib/ably/exceptions.rb

@@ -1,6 +1,7 @@
 module Ably
   module Exceptions
-    # An invalid request was received by Ably
+    # Base Ably exception class that contains status and code values used by Ably
+    # Refer to https://github.com/ably/ably-common/blob/master/protocol/errors.json
     #
     # @!attribute [r] message
     #   @return [String] Error message from Ably
@@ -8,19 +9,22 @@ module Ably
     #   @return [String] HTTP status code of error
     # @!attribute [r] code
     #   @return [String] Ably specific error code
-    class InvalidRequest < StandardError
+    class Base < StandardError
       attr_reader :status, :code
-      def initialize(message, status: nil, code: nil)
+      def initialize(message, status = nil, code = nil)
         super message
         @status = status
         @code = code
       end
     end
 
+    # An invalid request was received by Ably
+    class InvalidRequest < Base; end
+
     # The HTTP request has returned a 500 error
     class ServerError < StandardError; end
 
-    # PagedResource cannot retrieve the page
+    # PaginatedResource cannot retrieve the page
     class InvalidPageError < StandardError; end
 
     # The expected response from the server was invalid
@@ -33,9 +37,16 @@ module Ably
     class TokenRequestError < StandardError; end
 
     # The token is invalid
-    class InvalidToken < InvalidRequest; end
+    class InvalidToken < Base; end
 
     # Encryption or decryption related failures
     class EncryptionError < StandardError; end
+
+    # Ably Protocol message received that is invalid
+    class ProtocolError < Base; end
+
+    # A generic Ably exception taht supports a status & code.
+    # See https://github.com/ably/ably-common/blob/master/protocol/errors.json for a list of Ably errors
+    class Standard < Base; end
   end
 end

data/lib/ably/{realtime/models → models}/error_info.rb

@@ -1,4 +1,4 @@
-module Ably::Realtime::Models
+module Ably::Models
   # An exception type encapsulating error information containing
   # an Ably-specific error code and generic status code.
   #
@@ -8,29 +8,27 @@ module Ably::Realtime::Models
   #   @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
+  # @!attribute [r] hash
   #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
   #
   class ErrorInfo
-    include Shared
-    include Ably::Modules::Conversions
+    include Ably::Modules::ModelCommon
 
-    def initialize(json_object)
-      @raw_json_object = json_object
-      @json_object     = IdiomaticRubyWrapper(@raw_json_object.clone.freeze)
+    def initialize(hash_object)
+      @raw_hash_object = hash_object
+      @hash_object     = IdiomaticRubyWrapper(hash_object.clone.freeze)
     end
 
     %w( message code status_code ).each do |attribute|
       define_method attribute do
-        json[attribute.to_sym]
+        hash[attribute.to_sym]
       end
     end
     alias_method :status, :status_code
 
-    def json
-      @json_object
+    def hash
+      @hash_object
     end
-    alias_method :to_json, :json
 
     def to_s
       "Error: #{message} (code: #{code}, status_code: #{status_code})"

data/lib/ably/models/idiomatic_ruby_wrapper.rb

@@ -18,7 +18,7 @@ module Ably::Modules
 end
 
 module Ably::Models
-  # Wraps JSON objects returned by Ably service to appear as Idiomatic Ruby Hashes with symbol keys
+  # Wraps Hash objects returned by Ably service to appear as Idiomatic Ruby Hashes with symbol keys
   # It recursively wraps containing Hashes, but will stop wrapping at arrays, any other non Hash object, or any key matching the `:stops_at` options
   # It also provides methods matching the symbolic keys for convenience
   #
@@ -36,32 +36,33 @@ module Ably::Models
   #   ruby_hash.none # => nil
   #
   # @!attribute [r] stop_at
-  #   @return [Array<Symbol,String>] array of keys that this wrapper should stop wrapping at to preserve the underlying JSON hash as is
+  #   @return [Array<Symbol,String>] array of keys that this wrapper should stop wrapping at to preserve the underlying Hash as is
   #
   class IdiomaticRubyWrapper
     include Enumerable
     include Ably::Modules::Conversions
+    include Ably::Modules::MessagePack
 
     attr_reader :stop_at
 
-    # Creates an IdiomaticRubyWrapper around the mixed case JSON object
+    # Creates an IdiomaticRubyWrapper around the mixed case Hash object
     #
-    # @attribute [Hash] mixedCaseJsonObject mixed case JSON object
-    # @attribute [Array<Symbol,String>] stop_at array of keys that this wrapper should stop wrapping at to preserve the underlying JSON hash as is
+    # @attribute [Hash] mixedCaseHashObject mixed case Hash object
+    # @attribute [Array<Symbol,String>] stop_at array of keys that this wrapper should stop wrapping at to preserve the underlying Hash as is
     #
-    def initialize(mixedCaseJsonObject, stop_at: [])
-      if mixedCaseJsonObject.kind_of?(IdiomaticRubyWrapper)
+    def initialize(mixedCaseHashObject, stop_at: [])
+      if mixedCaseHashObject.kind_of?(IdiomaticRubyWrapper)
         $stderr.puts "<IdiomaticRubyWrapper#initialize> WARNING: Wrapping a IdiomaticRubyWrapper with another IdiomaticRubyWrapper"
       end
 
-      @json = mixedCaseJsonObject
+      @hash = mixedCaseHashObject
       @stop_at = Array(stop_at).each_with_object({}) do |key, hash|
         hash[convert_to_snake_case_symbol(key)] = true
       end.freeze
     end
 
     def [](key)
-      value = json[source_key_for(key)]
+      value = hash[source_key_for(key)]
       if stop_at?(key) || !value.kind_of?(Hash)
         value
       else
@@ -70,7 +71,7 @@ module Ably::Models
     end
 
     def []=(key, value)
-      json[source_key_for(key)] = value
+      hash[source_key_for(key)] = value
     end
 
     def fetch(key, default = nil, &missing_block)
@@ -88,7 +89,7 @@ module Ably::Models
     end
 
     def size
-      json.size
+      hash.size
     end
 
     def keys
@@ -100,12 +101,12 @@ module Ably::Models
     end
 
     def has_key?(key)
-      json.has_key?(source_key_for(key))
+      hash.has_key?(source_key_for(key))
     end
 
     # Method ensuring this {IdiomaticRubyWrapper} is {http://ruby-doc.org/core-2.1.3/Enumerable.html Enumerable}
     def each(&block)
-      json.each do |key, value|
+      hash.each do |key, value|
         key = convert_to_snake_case_symbol(key)
         value = self[key]
         if block_given?
@@ -137,29 +138,59 @@ module Ably::Models
       end
     end
 
-    # Access to the raw JSON object provided to the constructer of this wrapper
-    def json
-      @json
+    # Access to the raw Hash object provided to the constructer of this wrapper
+    def hash
+      @hash
     end
 
-    # Converts the current wrapped mixedCase object to a JSON string
-    # using the provided mixedCase syntax
+    # Takes the underlying Hash object and returns it in as a JSON ready Hash object using snakeCase for compability with the Ably service.
+    # Note name clashes are ignored and will result in loss of one or more values
+    # @example
+    #   wrapper = IdiomaticRubyWrapper({ 'mixedCase': true, mixed_case: false, 'snake_case': 1 })
+    #   wrapper.as_json({ 'mixedCase': true, 'snakeCase': 1 })
+    def as_json(*args)
+      hash.each_with_object({}) do |key_val, new_hash|
+        key, val                 = key_val
+        mixed_case_key           = convert_to_mixed_case(key)
+        wrapped_val              = self[key]
+        wrapped_val              = wrapped_val.as_json(args) if wrapped_val.kind_of?(IdiomaticRubyWrapper)
+
+        new_hash[mixed_case_key] = wrapped_val
+      end
+    end
+
+    # Converts the current wrapped mixedCase object to JSON
+    # using mixedCase syntax as expected by the Realtime API
     def to_json(*args)
-      json.to_json
+      as_json(args).to_json
     end
 
-    # Generate a symbolized Hash object representing the underlying JSON in a Ruby friendly format
-    def to_hash
+    # Generate a symbolized Hash object representing the underlying Hash in a Ruby friendly format.
+    # Note name clashes are ignored and will result in loss of one or more values
+    # @example
+    #   wrapper = IdiomaticRubyWrapper({ 'mixedCase': true, mixed_case: false, 'snake_case': 1 })
+    #   wrapper.to_hash({ mixed_case: true, snake_case: 1 })
+    def to_hash(*args)
       each_with_object({}) do |key_val, hash|
-        key, val = key_val
+        key, val  = key_val
+        val       = val.to_hash(args) if val.kind_of?(IdiomaticRubyWrapper)
         hash[key] = val
       end
     end
 
-    # Method to create a duplicate of the underlying JSON object
-    # Useful when underlying JSON is frozen
+    # Method to create a duplicate of the underlying Hash object
+    # Useful when underlying Hash is frozen
     def dup
-      Ably::Models::IdiomaticRubyWrapper.new(json.dup)
+      Ably::Models::IdiomaticRubyWrapper.new(hash.dup)
+    end
+
+    # Freeze the underlying data
+    def freeze
+      hash.freeze
+    end
+
+    def to_s
+      hash.to_s
     end
 
     private
@@ -183,7 +214,7 @@ module Ably::Models
       ]
 
       preferred_format = format_preferences.detect do |format|
-        json.has_key?(format.call(symbolized_key))
+        hash.has_key?(format.call(symbolized_key))
       end || format_preferences.first
 
       preferred_format.call(symbolized_key)