ably 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3b4423dc2ad92073b07e69cb72a3acbbe2d0973a
+  data.tar.gz: 76c5bb17b624875ec6fea9300c3778b216635266
+SHA512:
+  metadata.gz: e107b6875dbfc0bd05ba14c48b37bb0d6fea3d514666353495ff12c822bcc62f09322a3442eed5239ccf1ac1df466e48cb59387970be373260bfb9c40f28dce2
+  data.tar.gz: aa9f928e0f48b74cb158d8f0b7b8d21dec755427b02bff93d8f73fd6233be0ec4f8a5926acfd7ee0de3d6e6c3aff364f005122b561d7db4ee18aa6c169934703

data/.gitignore

@@ -0,0 +1,4 @@
+Gemfile.lock
+.yardoc
+doc/*
+pkg

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ably.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Lewis Marshall
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# Ably
+
+A Ruby client library for [ably.io](https://ably.io), the real-time messaging service.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'ably'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ably
+
+## Using the Realtime API
+
+### Subscribing to a channel
+
+Given:
+
+```
+client = Ably::Realtime.new(api_key: "xxxxx")
+
+channel = client.channel("test")
+```
+
+Subscribe to all events:
+
+```
+channel.subscribe do |message|
+  message[:name] #=> "greeting"
+  message[:data] #=> "Hello World!"
+end
+```
+
+Only certain events:
+
+```
+channel.subscribe("myEvent") do |message|
+  message[:name] #=> "myEvent"
+  message[:data] #=> "myData"
+end
+```
+
+### Publishing to a channel
+
+```
+client = Ably::Realtime.new(api_key: "xxxxx")
+
+channel = client.channel("test")
+
+channel.publish("greeting", "Hello World!")
+```
+
+## Using the REST API
+
+### Publishing a message to a channel
+
+```
+client = Ably::Rest.new(api_key: "xxxxx")
+
+channel = client.channel("test")
+
+channel.publish("myEvent", "Hello!") #=> true
+```
+
+### Fetching a channel's history
+
+```
+client = Ably::Rest.new(api_key: "xxxxx")
+
+channel = client.channel("test")
+
+channel.history #=> [{:name=>"test", :data=>"payload"}]
+```
+
+### Fetching your application's stats
+
+```
+client = Ably::Rest.new(api_key: "xxxxx")
+
+client.stats #=> [{:channels=>..., :apiRequests=>..., ...}]
+```
+
+### Fetching the Ably service time
+
+```
+client = Ably::Rest.new(api_key: "xxxxx")
+
+client.time #=> 2013-12-12 14:23:34 +0000
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+
+require "yard"
+YARD::Rake::YardocTask.new

data/ably.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ably/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ably"
+  spec.version       = Ably::VERSION
+  spec.authors       = ["Lewis Marshall", "Matthew O'Riordan"]
+  spec.email         = ["lewis@lmars.net", "matt@ably.io"]
+  spec.description   = %q{A Ruby client library for ably.io, the real-time messaging service}
+  spec.summary       = %q{A Ruby client library for ably.io, the real-time messaging service}
+  spec.homepage      = "http://github.com/ably/ably-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "eventmachine"
+  spec.add_runtime_dependency "faraday", "~> 0.9"
+  spec.add_runtime_dependency "json"
+  spec.add_runtime_dependency "websocket-driver"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "redcarpet"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "webmock"
+end

data/lib/ably.rb

@@ -0,0 +1,11 @@
+require "ably/support"
+
+require "ably/auth"
+require "ably/exceptions"
+require "ably/rest"
+require "ably/realtime"
+require "ably/token"
+require "ably/version"
+
+module Ably
+end

data/lib/ably/auth.rb

@@ -0,0 +1,381 @@
+require "json"
+require "faraday"
+require "securerandom"
+
+require "ably/rest/middleware/external_exceptions"
+require "ably/rest/middleware/parse_json"
+
+module Ably
+  # Auth is responsible for authentication with {https://ably.io Ably} using basic or token authentication
+  #
+  # Find out more about Ably authentication at: http://docs.ably.io/other/authentication/
+  #
+  # @!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
+  # @!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
+  #   @return [String] Complete API key containing both the key ID and key secret, if present
+  # @!attribute [r] key_id
+  #   @return [String] Key ID (public part of the API key), if present
+  # @!attribute [r] key_secret
+  #   @return [String] Key secret (private secure part of the API key), if present
+  # @!attribute [r] options
+  #   @return [Hash] {Ably::Auth} options configured for this client
+
+  class Auth
+    include Ably::Support
+
+    attr_reader :options, :current_token
+    alias_method :auth_options, :options
+
+    # Creates an Auth object
+    #
+    # @param [Ably::Rest::Client] client  {Ably::Rest::Client} this Auth object uses
+    # @param [Hash] auth_options          see {Ably::Rest::Client#initialize}
+    # @yield [auth_options]               see {Ably::Rest::Client#initialize}
+    def initialize(client, auth_options, &auth_block)
+      @client        = client
+      @options       = auth_options
+      @auth_callback = auth_block if block_given?
+
+      unless auth_options.kind_of?(Hash)
+        raise ArgumentError, "Expected auth_options to be a Hash"
+      end
+
+      if auth_options[:api_key] && (auth_options[:key_secret] || auth_options[:key_id])
+        raise ArgumentError, "api_key and key_id or key_secret are mutually exclusive. Provider either an api_key or key_id & key_secret"
+      end
+
+      if auth_options[:api_key]
+        api_key_parts = auth_options[:api_key].to_s.match(/(?<id>[\w_-]+\.[\w_-]+):(?<secret>[\w_-]+)/)
+        raise ArgumentError, "api_key is invalid" unless api_key_parts
+        auth_options[:key_id] = api_key_parts[:id]
+        auth_options[:key_secret] = api_key_parts[:secret]
+      end
+
+      if using_basic_auth? && !api_key_present?
+        raise ArgumentError, "api_key is missing. Either an API key, token, or token auth method must be provided"
+      end
+
+      if has_client_id? && !api_key_present?
+        raise ArgumentError, "client_id cannot be provided without a complete API key. Key ID & Secret is needed to authenticate with Ably and obtain a token"
+      end
+
+      @options.freeze
+    end
+
+    # Ensures valid auth credentials are present for the library instance. This may rely on an already-known and valid token, and will obtain a new token if necessary.
+    #
+    # In the event that a new token request is made, the specified options are used.
+    #
+    # @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)
+    # @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 [Boolean] :force        obtains a new token even if the current token is valid
+    #
+    # @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}
+    #
+    # @return [Ably::Token]
+    #
+    # @example
+    #    # will issue a simple token request using basic auth
+    #    client = Ably::Rest::Client.new(api_key: 'key.id:secret')
+    #    token = client.auth.authorise
+    #
+    #    # will use token request from block to authorise if not already authorised
+    #    token = client.auth.authorise do |options|
+    #      # create token_request object
+    #      token_request
+    #    end
+    #
+    def authorise(options = {}, &block)
+      if !options[:force] && current_token
+        return current_token unless current_token.expired?
+      end
+
+      @current_token = request_token(options, &block)
+    end
+
+    # Request a {Ably::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)
+    # @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
+    #
+    # @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}
+    #
+    # @return [Ably::Token]
+    #
+    # @example
+    #    # simple token request using basic auth
+    #    client = Ably::Rest::Client.new(api_key: 'key.id:secret')
+    #    token = client.auth.request_token
+    #
+    #    # token request using auth block
+    #    token = client.auth.request_token do |options|
+    #      # create token_request object
+    #      token_request
+    #    end
+    #
+    def request_token(options = {}, &block)
+      token_options = self.auth_options.merge(options)
+
+      auth_url = token_options.delete(:auth_url)
+      token_request = if block_given?
+        yield(token_options)
+      elsif auth_callback
+        auth_callback.call(token_options)
+      elsif auth_url
+        token_request_from_auth_url(auth_url, token_options)
+      else
+        create_token_request(token_options)
+      end
+
+      response = client.post("/keys/#{token_request.fetch(:id)}/requestToken", token_request, send_auth_header: false)
+
+      Ably::Token.new(response.body[:access_token])
+    end
+
+    # Creates and signs a token request that can then subsequently be used by any client to request a token
+    #
+    # @param [Hash] options the options for the token request
+    # @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 [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
+    # @return [Hash]
+    #
+    # @example
+    #    client.auth.create_request_token(id: 'asd.asd', ttl: 3600)
+    #    # => {
+    #    #   :id=>"asds.adsa",
+    #    #   :client_id=>nil,
+    #    #   :ttl=>3600,
+    #    #   :timestamp=>1410718527,
+    #    #   :capability=>"{\"*\":[\"*\"]}",
+    #    #   :nonce=>"95e543b88299f6bae83df9b12fbd1ecd",
+    #    #   :mac=>"881oZHeFo6oMim7N64y2vFHtSlpQ2gn/uE56a8gUxHw="
+    #    # }
+    def create_token_request(options = {})
+      token_attributes   = %w(id client_id ttl timestamp capability nonce)
+
+      token_options      = options.dup
+      request_key_id     = token_options.delete(:key_id) || key_id
+      request_key_secret = token_options.delete(:key_secret) || key_secret
+
+      raise TokenRequestError, "Key ID and Key Secret are required to generate a new token request" unless request_key_id && request_key_secret
+
+      timestamp = if token_options[:query_time]
+        client.time
+      else
+        Time.now
+      end.to_i
+
+      token_request = {
+        id:         request_key_id,
+        client_id:  client_id,
+        ttl:        Token::DEFAULTS[:ttl],
+        timestamp:  timestamp,
+        capability: Token::DEFAULTS[:capability],
+        nonce:      SecureRandom.hex
+      }.merge(token_options.select { |key, val| token_attributes.include?(key.to_s) })
+
+      if token_request[:capability].is_a?(Hash)
+        token_request[:capability] = token_request[:capability].to_json
+      end
+
+      token_request[:mac] = sign_params(token_request, request_key_secret)
+
+      token_request
+    end
+
+    def api_key
+      "#{key_id}:#{key_secret}" if api_key_present?
+    end
+
+    def key_id
+      options[:key_id]
+    end
+
+    def key_secret
+      options[:key_secret]
+    end
+
+    # True when Basic Auth is being used to authenticate with Ably
+    def using_basic_auth?
+      !using_token_auth?
+    end
+
+    # True when Token Auth is being used to authenticate with Ably
+    def using_token_auth?
+      token_id || current_token || has_client_id? || token_creatable_externally?
+    end
+
+    def client_id
+      options[:client_id]
+    end
+
+    def token_id
+      options[:token_id]
+    end
+
+    # Auth header string used in HTTP requests to Ably
+    #
+    # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
+    def auth_header
+      if using_token_auth?
+        token_auth_header
+      else
+        basic_auth_header
+      end
+    end
+
+    private
+    attr_reader :auth_callback
+
+    def basic_auth_header
+      raise InsecureRequestError, "Cannot use Basic Auth over non-TLS connections" unless client.use_tls?
+      "Basic #{encode64("#{api_key}")}"
+    end
+
+    def token_auth_header
+      current_token_id = if token_id
+        token_id
+      else
+        authorise.id
+      end
+
+      "Bearer #{encode64(current_token_id)}"
+    end
+
+    # Sign the request params using the secret
+    #
+    # @return [Hash]
+    def sign_params(params, secret)
+      text = params.values_at(
+        :id,
+        :ttl,
+        :capability,
+        :client_id,
+        :timestamp,
+        :nonce
+      ).map { |t| "#{t}\n" }.join("")
+
+      encode64(
+        Digest::HMAC.digest(text, secret, Digest::SHA256)
+      )
+    end
+
+    # Retrieve a token request from a specified URL, expects a JSON response
+    #
+    # @return [Hash]
+    def token_request_from_auth_url(auth_url, options = {})
+      uri = URI.parse(auth_url)
+      connection = Faraday.new("#{uri.scheme}://#{uri.host}", connection_options)
+      method = options[:auth_method] || :get
+
+      connection.send(method) do |request|
+        request.url uri.path
+        request.params = options[:auth_params] || {}
+        request.headers = options[:auth_headers] || {}
+      end.body
+    end
+
+    # Return a Hash of connection options to initiate the Faraday::Connection with
+    #
+    # @return [Hash]
+    def connection_options
+      @connection_options ||= {
+        builder: middleware,
+        headers: {
+          accept:     "application/json",
+          user_agent: user_agent
+        },
+        request: {
+          open_timeout: 5,
+          timeout:      10
+        }
+      }
+    end
+
+    # Return a Faraday middleware stack to initiate the Faraday::Connection with
+    #
+    # @see http://mislav.uniqpath.com/2011/07/faraday-advanced-http/
+    def middleware
+      @middleware ||= Faraday::RackBuilder.new do |builder|
+        # Convert request params to "www-form-urlencoded"
+        builder.use Faraday::Request::UrlEncoded
+
+        # Parse JSON response bodies
+        builder.use Ably::Rest::Middleware::ParseJson
+
+        # Log HTTP requests if debug_http option set
+        builder.response :logger if @debug_http
+
+        # Raise exceptions if response code is invalid
+        builder.use Ably::Rest::Middleware::ExternalExceptions
+
+        # Set Faraday's HTTP adapter
+        builder.adapter Faraday.default_adapter
+      end
+    end
+
+    def token_callback_present?
+      !!auth_callback
+    end
+
+    def token_url_present?
+      !!options[:auth_url]
+    end
+
+    def token_creatable_externally?
+      token_callback_present? || token_url_present?
+    end
+
+    def token_renewable?
+      use_basic_auth? || token_creatable_externally?
+    end
+
+    def has_client_id?
+      !!client_id
+    end
+
+    def api_key_present?
+      key_id && key_secret
+    end
+
+    private
+    attr_reader :client
+  end
+end