restforce 0.1.8 → 0.1.9

data/README.md

@@ -15,7 +15,7 @@ It attempts to solve a couple of key issues that the databasedotcom gem has been
 * A clean and modular architecture using [Faraday middleware](https://github.com/technoweenie/faraday)
 * Support for decoding [Force.com Canvas](http://www.salesforce.com/us/developer/docs/platform_connectpre/canvas_framework.pdf) signed requests. (NEW!)
 
-[Documentation](http://rubydoc.info/gems/restforce/frames)
+[Documentation](http://rubydoc.info/gems/restforce/frames) | [Changelog](http://revision.io/restforce)
 
 ## Installation
 
@@ -98,7 +98,7 @@ Restforce.configure do |config|
 end
 ```
 
-### Bang methods
+### Bang! methods
 
 All the CRUD methods (create, update, upsert, destroy) have equivalent methods with 
 a ! at the end (create!, update!, upsert!, destroy!), which can be used if you need
@@ -294,9 +294,6 @@ require 'faye'
 # Initialize a client with your username/password/oauth token/etc.
 client = Restforce.new
 
-# Force an authentication request.
-client.authenticate!
-
 # Create a PushTopic for subscribing to Account changes.
 client.create! 'PushTopic', {
   ApiVersion: '23.0',
@@ -372,6 +369,10 @@ ActiveSupport::Notifications.subscribe('request.faraday') do |name, start, finis
 end
 ```
 
+## Force.com Canvas
+
+You can use Restforce to decode signed requests from Salesforce. See [the example app](https://gist.github.com/4052312).
+
 ## Contributing
 
 1. Fork it

data/lib/restforce/client.rb

@@ -1,5 +1,19 @@
+require 'restforce/client/connection'
+require 'restforce/client/authentication'
+require 'restforce/client/streaming'
+require 'restforce/client/caching'
+require 'restforce/client/canvas'
+require 'restforce/client/api'
+
 module Restforce
   class Client
+    include Restforce::Client::Connection
+    include Restforce::Client::Authentication
+    include Restforce::Client::Streaming
+    include Restforce::Client::Caching
+    include Restforce::Client::Canvas
+    include Restforce::Client::API
+
     OPTIONS = [:username, :password, :security_token, :client_id, :client_secret, :host, :compress,
        :api_version, :oauth_token, :refresh_token, :instance_url, :cache, :authentication_retries]
 
@@ -63,378 +77,5 @@ module Restforce
       @options = Hash[OPTIONS.map { |option| [option, Restforce.configuration.send(option)] }]
       @options.merge! opts
     end
-
-    # Public: Get the names of all sobjects on the org.
-    #
-    # Examples
-    #
-    #   # get the names of all sobjects on the org
-    #   client.list_sobjects
-    #   # => ['Account', 'Lead', ... ]
-    #
-    # Returns an Array of String names for each SObject.
-    def list_sobjects
-      describe.collect { |sobject| sobject['name'] }
-    end
-    
-    # Public: Returns a detailed describe result for the specified sobject
-    #
-    # sobject - Stringish name of the sobject (default: nil).
-    #
-    # Examples
-    #
-    #   # get the global describe for all sobjects
-    #   client.describe
-    #   # => { ... }
-    #
-    #   # get the describe for the Account object
-    #   client.describe('Account')
-    #   # => { ... }
-    #
-    # Returns the Hash representation of the describe call.
-    def describe(sobject=nil)
-      if sobject
-        api_get("sobjects/#{sobject.to_s}/describe").body
-      else
-        api_get('sobjects').body['sobjects']
-      end
-    end
-
-    # Public: Get the current organization's Id.
-    #
-    # Examples
-    #
-    #   client.org_id
-    #   # => '00Dx0000000BV7z'
-    #
-    # Returns the String organization Id
-    def org_id
-      query('select id from Organization').first['Id']
-    end
-    
-    # Public: Executs a SOQL query and returns the result.
-    #
-    # soql - A SOQL expression.
-    #
-    # Examples
-    #
-    #   # Find the names of all Accounts
-    #   client.query('select Name from Account').map(&:Name)
-    #   # => ['Foo Bar Inc.', 'Whizbang Corp']
-    #
-    # Returns a Restforce::Collection if Restforce.configuration.mashify is true.
-    # Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.
-    def query(soql)
-      response = api_get 'query', :q => soql
-      mashify? ? response.body : response.body['records']
-    end
-    
-    # Public: Perform a SOSL search
-    #
-    # sosl - A SOSL expression.
-    #
-    # Examples
-    #
-    #   # Find all occurrences of 'bar'
-    #   client.search('FIND {bar}')
-    #   # => #<Restforce::Collection >
-    #
-    #   # Find accounts match the term 'genepoint' and return the Name field
-    #   client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
-    #   # => ['GenePoint']
-    #
-    # Returns a Restforce::Collection if Restforce.configuration.mashify is true.
-    # Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.
-    def search(sosl)
-      api_get('search', :q => sosl).body
-    end
-    
-    # Public: Insert a new record.
-    #
-    # Examples
-    #
-    #   # Add a new account
-    #   client.create('Account', Name: 'Foobar Inc.')
-    #   # => '0016000000MRatd'
-    #
-    # Returns the String Id of the newly created sobject. Returns false if
-    # something bad happens
-    def create(sobject, attrs)
-      create!(sobject, attrs)
-    rescue *exceptions
-      false
-    end
-    alias_method :insert, :create
-
-    # See .create
-    #
-    # Returns the String Id of the newly created sobject. Raises an error if
-    # something bad happens.
-    def create!(sobject, attrs)
-      api_post("sobjects/#{sobject}", attrs).body['id']
-    end
-    alias_method :insert!, :create!
-
-    # Public: Update a record.
-    #
-    # Examples
-    #
-    #   # Update the Account with Id '0016000000MRatd'
-    #   client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
-    #
-    # Returns true if the sobject was successfully updated, false otherwise.
-    def update(sobject, attrs)
-      update!(sobject, attrs)
-    rescue *exceptions
-      false
-    end
-
-    # See .update
-    #
-    # Returns true if the sobject was successfully updated, raises an error
-    # otherwise.
-    def update!(sobject, attrs)
-      id = attrs.has_key?(:Id) ? attrs.delete(:Id) : attrs.delete('Id')
-      raise 'Id field missing.' unless id
-      api_patch "sobjects/#{sobject}/#{id}", attrs
-      true
-    end
-
-    # Public: Update or Create a record based on an external ID
-    #
-    # sobject - The name of the sobject to created.
-    # field   - The name of the external Id field to match against.
-    # attrs   - Hash of attributes for the record.
-    #
-    # Examples
-    #
-    #   # Update the record with external ID of 12
-    #   client.upsert('Account', 'External__c', External__c: 12, Name: 'Foobar')
-    #
-    # Returns true if the record was found and updated.
-    # Returns the Id of the newly created record if the record was created.
-    # Returns false if something bad happens.
-    def upsert(sobject, field, attrs)
-      upsert!(sobject, field, attrs)
-    rescue *exceptions
-      false
-    end
-
-    # See .upsert
-    #
-    # Returns true if the record was found and updated.
-    # Returns the Id of the newly created record if the record was created.
-    # Raises an error if something bad happens.
-    def upsert!(sobject, field, attrs)
-      external_id = attrs.has_key?(field.to_sym) ? attrs.delete(field.to_sym) : attrs.delete(field.to_s)
-      response = api_patch "sobjects/#{sobject}/#{field.to_s}/#{external_id}", attrs
-      (response.body && response.body['id']) ? response.body['id'] : true
-    end
-
-    # Public: Delete a record.
-    #
-    # Examples
-    #
-    #   # Delete the Account with Id '0016000000MRatd'
-    #   client.delete('Account', '0016000000MRatd')
-    #
-    # Returns true if the sobject was successfully deleted, false otherwise.
-    def destroy(sobject, id)
-      destroy!(sobject, id)
-    rescue *exceptions
-      false
-    end
-
-    # See .destroy
-    #
-    # Returns true of the sobject was successfully deleted, raises an error
-    # otherwise.
-    def destroy!(sobject, id)
-      api_delete "sobjects/#{sobject}/#{id}"
-      true
-    end
-
-    # Public: Runs the block with caching disabled.
-    #
-    # block - A query/describe/etc.
-    #
-    # Returns the result of the block
-    def without_caching(&block)
-      @options[:perform_caching] = false
-      block.call
-    ensure
-      @options.delete(:perform_caching)
-    end
-
-    # Public: Subscribe to a PushTopic
-    #
-    # channel - The name of the PushTopic channel to subscribe to.
-    # block   - A block to run when a new message is received.
-    #
-    # Returns a Faye::Subscription
-    def subscribe(channel, &block)
-      faye.subscribe "/topic/#{channel}", &block
-    end
-
-    # Public: Force an authentication
-    def authenticate!
-      raise 'No authentication middleware present' unless authentication_middleware
-      middleware = authentication_middleware.new nil, self, @options
-      middleware.authenticate!
-    end
-
-    # Public: Decodes a signed request received from Force.com Canvas.
-    #
-    # message - The POST message containing the signed request from Salesforce.
-    #
-    # Returns the Hash context if the message is valid.
-    def decode_signed_request(message)
-      raise 'client_secret not set' unless @options[:client_secret]
-      Restforce.decode_signed_request(message, @options[:client_secret])
-    end
-
-    # Public: Helper methods for performing arbitrary actions against the API using
-    # various HTTP verbs.
-    #
-    # Examples
-    #
-    #   # Perform a get request
-    #   client.get '/services/data/v24.0/sobjects'
-    #   client.api_get 'sobjects'
-    #
-    #   # Perform a post request
-    #   client.post '/services/data/v24.0/sobjects/Account', { ... }
-    #   client.api_post 'sobjects/Account', { ... }
-    #
-    #   # Perform a put request
-    #   client.put '/services/data/v24.0/sobjects/Account/001D000000INjVe', { ... }
-    #   client.api_put 'sobjects/Account/001D000000INjVe', { ... }
-    #
-    #   # Perform a delete request
-    #   client.delete '/services/data/v24.0/sobjects/Account/001D000000INjVe'
-    #   client.api_delete 'sobjects/Account/001D000000INjVe'
-    #
-    # Returns the Faraday::Response.
-    [:get, :post, :put, :delete, :patch].each do |method|
-      define_method method do |*args|
-        retries = @options[:authentication_retries]
-        begin
-          connection.send(method, *args)
-        rescue Restforce::UnauthorizedError
-          if retries > 0
-            retries -= 1
-            connection.url_prefix = @options[:instance_url]
-            retry
-          end
-          raise
-        end
-      end
-
-      define_method :"api_#{method}" do |*args|
-        args[0] = api_path(args[0])
-        send(method, *args)
-      end
-    end
-
-    # Public: The Faraday::Builder instance used for the middleware stack. This
-    # can be used to insert an custom middleware.
-    #
-    # Examples
-    #
-    #   # Add the instrumentation middleware for Rails.
-    #   client.middleware.use FaradayMiddleware::Instrumentation
-    #
-    # Returns the Faraday::Builder for the Faraday connection.
-    def middleware
-      connection.builder
-    end
-
-  private
-
-    # Internal: Returns a path to an api endpoint
-    #
-    # Examples
-    #
-    #   api_path('sobjects')
-    #   # => '/services/data/v24.0/sobjects'
-    def api_path(path)
-      "/services/data/v#{@options[:api_version]}/#{path}"
-    end
-
-    # Internal: Internal faraday connection where all requests go through
-    def connection
-      @connection ||= Faraday.new(@options[:instance_url]) do |builder|
-        builder.use      Restforce::Middleware::Mashify, self, @options
-        builder.use      Restforce::Middleware::Multipart
-        builder.request  :json
-        builder.use      authentication_middleware, self, @options if authentication_middleware
-        builder.use      Restforce::Middleware::Authorization, self, @options
-        builder.use      Restforce::Middleware::InstanceURL, self, @options
-        builder.response :json
-        builder.use      Restforce::Middleware::Caching, cache, @options if cache
-        builder.use      FaradayMiddleware::FollowRedirects
-        builder.use      Restforce::Middleware::RaiseError
-        builder.use      Restforce::Middleware::Logger, Restforce.configuration.logger, @options if Restforce.log?
-        builder.use      Restforce::Middleware::Gzip, self, @options
-        builder.adapter  Faraday.default_adapter
-      end
-    end
-
-    # Internal: Determines what middleware will be used based on the options provided
-    def authentication_middleware
-      if username_password?
-        Restforce::Middleware::Authentication::Password
-      elsif oauth_refresh?
-        Restforce::Middleware::Authentication::Token
-      end
-    end
-
-    # Internal: Returns true if username/password (autonomous) flow should be used for
-    # authentication.
-    def username_password?
-      @options[:username] &&
-        @options[:password] &&
-        @options[:client_id] &&
-        @options[:client_secret]
-    end
-
-    # Internal: Returns true if oauth token refresh flow should be used for
-    # authentication.
-    def oauth_refresh?
-      @options[:refresh_token] &&
-        @options[:client_id] &&
-        @options[:client_secret]
-    end
-
-    # Internal: Cache to use for the caching middleware
-    def cache
-      @options[:cache]
-    end
-
-    # Internal: Returns true if the middlware stack includes the
-    # Restforce::Middleware::Mashify middleware.
-    def mashify?
-      middleware.handlers.index(Restforce::Middleware::Mashify)
-    end
-
-    # Internal: Errors that should be rescued from in non-bang methods
-    def exceptions
-      [Faraday::Error::ClientError]
-    end
-
-    # Internal: Faye client to use for subscribing to PushTopics
-    def faye
-      raise 'Instance URL missing. Call .authenticate! first.' unless @options[:instance_url]
-      @faye ||= Faye::Client.new("#{@options[:instance_url]}/cometd/#{@options[:api_version]}").tap do |client|
-        raise 'OAuth token missing. Call .authenticate! first.' unless @options[:oauth_token]
-        client.set_header 'Authorization', "OAuth #{@options[:oauth_token]}"
-        client.bind 'transport:down' do
-          Restforce.log "[COMETD DOWN]"
-        end
-        client.bind 'transport:up' do
-          Restforce.log "[COMETD UP]"
-        end
-      end
-    end
   end
 end

data/lib/restforce/client/api.rb

@@ -0,0 +1,257 @@
+module Restforce
+  class Client
+    module API
+
+      # Public: Get the names of all sobjects on the org.
+      #
+      # Examples
+      #
+      #   # get the names of all sobjects on the org
+      #   client.list_sobjects
+      #   # => ['Account', 'Lead', ... ]
+      #
+      # Returns an Array of String names for each SObject.
+      def list_sobjects
+        describe.collect { |sobject| sobject['name'] }
+      end
+      
+      # Public: Returns a detailed describe result for the specified sobject
+      #
+      # sobject - Stringish name of the sobject (default: nil).
+      #
+      # Examples
+      #
+      #   # get the global describe for all sobjects
+      #   client.describe
+      #   # => { ... }
+      #
+      #   # get the describe for the Account object
+      #   client.describe('Account')
+      #   # => { ... }
+      #
+      # Returns the Hash representation of the describe call.
+      def describe(sobject=nil)
+        if sobject
+          api_get("sobjects/#{sobject.to_s}/describe").body
+        else
+          api_get('sobjects').body['sobjects']
+        end
+      end
+
+      # Public: Get the current organization's Id.
+      #
+      # Examples
+      #
+      #   client.org_id
+      #   # => '00Dx0000000BV7z'
+      #
+      # Returns the String organization Id
+      def org_id
+        query('select id from Organization').first['Id']
+      end
+      
+      # Public: Executs a SOQL query and returns the result.
+      #
+      # soql - A SOQL expression.
+      #
+      # Examples
+      #
+      #   # Find the names of all Accounts
+      #   client.query('select Name from Account').map(&:Name)
+      #   # => ['Foo Bar Inc.', 'Whizbang Corp']
+      #
+      # Returns a Restforce::Collection if Restforce.configuration.mashify is true.
+      # Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.
+      def query(soql)
+        response = api_get 'query', :q => soql
+        mashify? ? response.body : response.body['records']
+      end
+      
+      # Public: Perform a SOSL search
+      #
+      # sosl - A SOSL expression.
+      #
+      # Examples
+      #
+      #   # Find all occurrences of 'bar'
+      #   client.search('FIND {bar}')
+      #   # => #<Restforce::Collection >
+      #
+      #   # Find accounts match the term 'genepoint' and return the Name field
+      #   client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
+      #   # => ['GenePoint']
+      #
+      # Returns a Restforce::Collection if Restforce.configuration.mashify is true.
+      # Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.
+      def search(sosl)
+        api_get('search', :q => sosl).body
+      end
+      
+      # Public: Insert a new record.
+      #
+      # Examples
+      #
+      #   # Add a new account
+      #   client.create('Account', Name: 'Foobar Inc.')
+      #   # => '0016000000MRatd'
+      #
+      # Returns the String Id of the newly created sobject. Returns false if
+      # something bad happens
+      def create(sobject, attrs)
+        create!(sobject, attrs)
+      rescue *exceptions
+        false
+      end
+      alias_method :insert, :create
+
+      # See .create
+      #
+      # Returns the String Id of the newly created sobject. Raises an error if
+      # something bad happens.
+      def create!(sobject, attrs)
+        api_post("sobjects/#{sobject}", attrs).body['id']
+      end
+      alias_method :insert!, :create!
+
+      # Public: Update a record.
+      #
+      # Examples
+      #
+      #   # Update the Account with Id '0016000000MRatd'
+      #   client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
+      #
+      # Returns true if the sobject was successfully updated, false otherwise.
+      def update(sobject, attrs)
+        update!(sobject, attrs)
+      rescue *exceptions
+        false
+      end
+
+      # See .update
+      #
+      # Returns true if the sobject was successfully updated, raises an error
+      # otherwise.
+      def update!(sobject, attrs)
+        id = attrs.has_key?(:Id) ? attrs.delete(:Id) : attrs.delete('Id')
+        raise 'Id field missing.' unless id
+        api_patch "sobjects/#{sobject}/#{id}", attrs
+        true
+      end
+
+      # Public: Update or Create a record based on an external ID
+      #
+      # sobject - The name of the sobject to created.
+      # field   - The name of the external Id field to match against.
+      # attrs   - Hash of attributes for the record.
+      #
+      # Examples
+      #
+      #   # Update the record with external ID of 12
+      #   client.upsert('Account', 'External__c', External__c: 12, Name: 'Foobar')
+      #
+      # Returns true if the record was found and updated.
+      # Returns the Id of the newly created record if the record was created.
+      # Returns false if something bad happens.
+      def upsert(sobject, field, attrs)
+        upsert!(sobject, field, attrs)
+      rescue *exceptions
+        false
+      end
+
+      # See .upsert
+      #
+      # Returns true if the record was found and updated.
+      # Returns the Id of the newly created record if the record was created.
+      # Raises an error if something bad happens.
+      def upsert!(sobject, field, attrs)
+        external_id = attrs.has_key?(field.to_sym) ? attrs.delete(field.to_sym) : attrs.delete(field.to_s)
+        response = api_patch "sobjects/#{sobject}/#{field.to_s}/#{external_id}", attrs
+        (response.body && response.body['id']) ? response.body['id'] : true
+      end
+
+      # Public: Delete a record.
+      #
+      # Examples
+      #
+      #   # Delete the Account with Id '0016000000MRatd'
+      #   client.delete('Account', '0016000000MRatd')
+      #
+      # Returns true if the sobject was successfully deleted, false otherwise.
+      def destroy(sobject, id)
+        destroy!(sobject, id)
+      rescue *exceptions
+        false
+      end
+
+      # See .destroy
+      #
+      # Returns true of the sobject was successfully deleted, raises an error
+      # otherwise.
+      def destroy!(sobject, id)
+        api_delete "sobjects/#{sobject}/#{id}"
+        true
+      end
+
+      # Public: Helper methods for performing arbitrary actions against the API using
+      # various HTTP verbs.
+      #
+      # Examples
+      #
+      #   # Perform a get request
+      #   client.get '/services/data/v24.0/sobjects'
+      #   client.api_get 'sobjects'
+      #
+      #   # Perform a post request
+      #   client.post '/services/data/v24.0/sobjects/Account', { ... }
+      #   client.api_post 'sobjects/Account', { ... }
+      #
+      #   # Perform a put request
+      #   client.put '/services/data/v24.0/sobjects/Account/001D000000INjVe', { ... }
+      #   client.api_put 'sobjects/Account/001D000000INjVe', { ... }
+      #
+      #   # Perform a delete request
+      #   client.delete '/services/data/v24.0/sobjects/Account/001D000000INjVe'
+      #   client.api_delete 'sobjects/Account/001D000000INjVe'
+      #
+      # Returns the Faraday::Response.
+      [:get, :post, :put, :delete, :patch].each do |method|
+        define_method method do |*args|
+          retries = @options[:authentication_retries]
+          begin
+            connection.send(method, *args)
+          rescue Restforce::UnauthorizedError
+            if retries > 0
+              retries -= 1
+              connection.url_prefix = @options[:instance_url]
+              retry
+            end
+            raise
+          end
+        end
+
+        define_method :"api_#{method}" do |*args|
+          args[0] = api_path(args[0])
+          send(method, *args)
+        end
+      end
+
+    private
+
+      # Internal: Returns a path to an api endpoint
+      #
+      # Examples
+      #
+      #   api_path('sobjects')
+      #   # => '/services/data/v24.0/sobjects'
+      def api_path(path)
+        "/services/data/v#{@options[:api_version]}/#{path}"
+      end
+
+      # Internal: Errors that should be rescued from in non-bang methods
+      def exceptions
+        [Faraday::Error::ClientError]
+      end
+
+    end
+  end
+end

data/lib/restforce/client/authentication.rb

@@ -0,0 +1,40 @@
+module Restforce
+  class Client
+    module Authentication
+
+      # Public: Force an authentication
+      def authenticate!
+        raise 'No authentication middleware present' unless authentication_middleware
+        middleware = authentication_middleware.new nil, self, @options
+        middleware.authenticate!
+      end
+
+      # Internal: Determines what middleware will be used based on the options provided
+      def authentication_middleware
+        if username_password?
+          Restforce::Middleware::Authentication::Password
+        elsif oauth_refresh?
+          Restforce::Middleware::Authentication::Token
+        end
+      end
+
+      # Internal: Returns true if username/password (autonomous) flow should be used for
+      # authentication.
+      def username_password?
+        @options[:username] &&
+          @options[:password] &&
+          @options[:client_id] &&
+          @options[:client_secret]
+      end
+
+      # Internal: Returns true if oauth token refresh flow should be used for
+      # authentication.
+      def oauth_refresh?
+        @options[:refresh_token] &&
+          @options[:client_id] &&
+          @options[:client_secret]
+      end
+
+    end
+  end
+end

data/lib/restforce/client/caching.rb

@@ -0,0 +1,26 @@
+module Restforce
+  class Client
+    module Caching
+
+      # Public: Runs the block with caching disabled.
+      #
+      # block - A query/describe/etc.
+      #
+      # Returns the result of the block
+      def without_caching(&block)
+        @options[:perform_caching] = false
+        block.call
+      ensure
+        @options.delete(:perform_caching)
+      end
+
+    private
+
+      # Internal: Cache to use for the caching middleware
+      def cache
+        @options[:cache]
+      end
+
+    end
+  end
+end

data/lib/restforce/client/canvas.rb

@@ -0,0 +1,17 @@
+module Restforce
+  class Client
+    module Canvas
+
+      # Public: Decodes a signed request received from Force.com Canvas.
+      #
+      # message - The POST message containing the signed request from Salesforce.
+      #
+      # Returns the Hash context if the message is valid.
+      def decode_signed_request(message)
+        raise 'client_secret not set' unless @options[:client_secret]
+        Restforce.decode_signed_request(message, @options[:client_secret])
+      end
+
+    end
+  end
+end

data/lib/restforce/client/connection.rb

@@ -0,0 +1,47 @@
+module Restforce
+  class Client
+    module Connection
+
+      # Public: The Faraday::Builder instance used for the middleware stack. This
+      # can be used to insert an custom middleware.
+      #
+      # Examples
+      #
+      #   # Add the instrumentation middleware for Rails.
+      #   client.middleware.use FaradayMiddleware::Instrumentation
+      #
+      # Returns the Faraday::Builder for the Faraday connection.
+      def middleware
+        connection.builder
+      end
+
+    private
+
+      # Internal: Internal faraday connection where all requests go through
+      def connection
+        @connection ||= Faraday.new(@options[:instance_url]) do |builder|
+          builder.use      Restforce::Middleware::Mashify, self, @options
+          builder.use      Restforce::Middleware::Multipart
+          builder.request  :json
+          builder.use      authentication_middleware, self, @options if authentication_middleware
+          builder.use      Restforce::Middleware::Authorization, self, @options
+          builder.use      Restforce::Middleware::InstanceURL, self, @options
+          builder.response :json
+          builder.use      Restforce::Middleware::Caching, cache, @options if cache
+          builder.use      FaradayMiddleware::FollowRedirects
+          builder.use      Restforce::Middleware::RaiseError
+          builder.use      Restforce::Middleware::Logger, Restforce.configuration.logger, @options if Restforce.log?
+          builder.use      Restforce::Middleware::Gzip, self, @options
+          builder.adapter  Faraday.default_adapter
+        end
+      end
+
+      # Internal: Returns true if the middlware stack includes the
+      # Restforce::Middleware::Mashify middleware.
+      def mashify?
+        middleware.handlers.index(Restforce::Middleware::Mashify)
+      end
+
+    end
+  end
+end

data/lib/restforce/client/streaming.rb

@@ -0,0 +1,31 @@
+module Restforce
+  class Client
+    module Streaming
+
+      # Public: Subscribe to a PushTopic
+      #
+      # channel - The name of the PushTopic channel to subscribe to.
+      # block   - A block to run when a new message is received.
+      #
+      # Returns a Faye::Subscription
+      def subscribe(channel, &block)
+        faye.subscribe "/topic/#{channel}", &block
+      end
+
+      # Public: Faye client to use for subscribing to PushTopics
+      def faye
+        raise 'Instance URL missing. Call .authenticate! first.' unless @options[:instance_url]
+        @faye ||= Faye::Client.new("#{@options[:instance_url]}/cometd/#{@options[:api_version]}").tap do |client|
+          client.bind 'transport:down' do
+            Restforce.log "[COMETD DOWN]"
+            client.set_header 'Authorization', "OAuth #{authenticate!.access_token}"
+          end
+          client.bind 'transport:up' do
+            Restforce.log "[COMETD UP]"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/restforce/sobject.rb

@@ -22,6 +22,11 @@ module Restforce
       @client.update(sobject_type, attrs)
     end
 
+    def save!
+      ensure_id
+      @client.update!(sobject_type, attrs)
+    end
+
     # Public: Destroy this record.
     #
     # Examples
@@ -33,6 +38,11 @@ module Restforce
       @client.destroy(sobject_type, self.Id)
     end
 
+    def destroy!
+      ensure_id
+      @client.destroy!(sobject_type, self.Id)
+    end
+
     # Public: Returns a hash representation of this object with the attributes
     # key and parent/child relationships removed.
     def attrs

data/lib/restforce/version.rb

@@ -1,3 +1,3 @@
 module Restforce
-  VERSION = '0.1.8'
+  VERSION = '0.1.9'
 end

data/spec/lib/client_spec.rb

@@ -424,12 +424,6 @@ shared_examples_for 'methods' do
   describe '.faye' do
     subject { client.send(:faye) }
 
-    context 'with missing oauth token' do
-      let(:instance_url) { 'http://foobar' }
-      let(:oauth_token) { nil }
-      specify { expect { subject }.to raise_error RuntimeError, 'OAuth token missing. Call .authenticate! first.' }
-    end
-
     context 'with missing instance url' do
       let(:instance_url) { nil }
       specify { expect { subject }.to raise_error RuntimeError, 'Instance URL missing. Call .authenticate! first.' }

data/spec/lib/sobject_spec.rb

@@ -59,7 +59,10 @@ describe Restforce::SObject do
     context 'when an Id is present' do
       before do
         hash.merge!(:Id => '001D000000INjVe')
-        @request = stub_api_request 'sobjects/Whizbang/001D000000INjVe', :method => :patch, :body => "{\"Checkbox_Label\":false,\"Text_Label\":\"Hi there!\",\"Date_Label\":\"2010-01-01\",\"DateTime_Label\":\"2011-07-07T00:37:00.000+0000\",\"Picklist_Multiselect_Label\":\"four;six\"}"
+        @request = stub_api_request 'sobjects/Whizbang/001D000000INjVe',
+          :method => :patch,
+          :body => "{\"Checkbox_Label\":false,\"Text_Label\":\"Hi there!\",\"Date_Label\":\"2010-01-01\"," +
+          "\"DateTime_Label\":\"2011-07-07T00:37:00.000+0000\",\"Picklist_Multiselect_Label\":\"four;six\"}"
       end
 
       after do
@@ -70,6 +73,26 @@ describe Restforce::SObject do
     end
   end
 
+  describe '.save!' do
+    subject { sobject.save! }
+
+    context 'when an exception is raised' do
+      before do
+        hash.merge!(:Id => '001D000000INjVe')
+        @request = stub_api_request 'sobjects/Whizbang/001D000000INjVe',
+          :with => 'sobject/delete_error_response',
+          :method => :patch,
+          :status => 404
+      end
+
+      after do
+        @request.should have_been_requested
+      end
+
+      specify { expect { subject }.to raise_error Faraday::Error::ResourceNotFound }
+    end
+  end
+
   describe '.destroy' do
     subject { sobject.destroy }
 
@@ -91,9 +114,30 @@ describe Restforce::SObject do
     end
   end
 
+  describe '.destroy!' do
+    subject { sobject.destroy! }
+
+    context 'when an exception is raised' do
+      before do
+        hash.merge!(:Id => '001D000000INjVe')
+        @request = stub_api_request 'sobjects/Whizbang/001D000000INjVe',
+          :with => 'sobject/delete_error_response',
+          :method => :delete,
+          :status => 404
+      end
+
+      after do
+        @request.should have_been_requested
+      end
+
+      specify { expect { subject }.to raise_error Faraday::Error::ResourceNotFound }
+    end
+  end
+
   describe '.describe' do
     before do
-      @request = stub_api_request 'sobjects/Whizbang/describe', :with => 'sobject/sobject_describe_success_response'
+      @request = stub_api_request 'sobjects/Whizbang/describe',
+        :with => 'sobject/sobject_describe_success_response'
     end
 
     after do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restforce
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-10 00:00:00.000000000 Z
+date: 2012-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -171,6 +171,12 @@ files:
 - Rakefile
 - lib/restforce.rb
 - lib/restforce/client.rb
+- lib/restforce/client/api.rb
+- lib/restforce/client/authentication.rb
+- lib/restforce/client/caching.rb
+- lib/restforce/client/canvas.rb
+- lib/restforce/client/connection.rb
+- lib/restforce/client/streaming.rb
 - lib/restforce/collection.rb
 - lib/restforce/config.rb
 - lib/restforce/mash.rb
@@ -251,12 +257,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -2351979982713256813
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -2351979982713256813
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23