defender 2.0.2 → 2.0.3

data/lib/defender.rb

@@ -1,66 +1,57 @@
-##
-# Main Defender module. Everything should be under this module.
+# Public: The main Defender module. This is the namespace under which all of
+# Defender is.
 module Defender
   autoload :VERSION, 'defender/version'
   autoload :Version, 'defender/version'
   autoload :Spammable, 'defender/spammable'
   autoload :DefenderError, 'defender/defender_error'
-  
-  ##
-  # Set this to your Defensio API key. Get one at http://defensio.com.
+
+  # Public: Set the Defensio API key. Get one at http://defensio.com.
   #
-  # @see Defender::Spammable::ClassMethods.configure_defender
+  # Defender will not work without a Defensio API key.
   #
-  # @param [String] api_key The Defensio API key.
+  # Returns the Defensio API key string.
   def self.api_key=(api_key)
     @api_key = api_key.to_s
   end
-  
-  ##
-  # Returns the Defensio API key set with {Defender.api_key=}.
-  #
-  # @see Defender.api_key=
-  # @return [String] The API key if set.
-  # @return [nil] If no API key has been set.
+
+  # Public: Returns the Defensio API key String set with #api_key=
   def self.api_key
     @api_key
   end
 
-  ##
-  # You most probably don't need to set this.  It is used to replace the backend
-  # when running the tests.  If you for any reason need to use another backend
-  # than the defensio gem, set this.  The object needs to respond to the same
-  # methods as the Defensio object does.
+  # Public: Returns whether Defender is in "test mode".
   #
-  # @param [Defensio] defensio The Defensio backend
+  # When in test mode, you can specify what kind of response you want in the
+  # content field. If you want a comment to be marked as spam with a
+  # spaminess of 0.85, you write [spam,0.85] somewhere in the content field
+  # of the document. If you want a malicious response with a spaminess of
+  # 0.99 you write [malicious,0.99], and for an innocent response you write
+  # [innocent,0.25]. This is the preferred way of testing, and if you test
+  # by writing "spammy" comments, you might hurt the Defensio performance.
+  def self.test_mode
+    !!@test_mode
+  end
+
+  # Public: Enables/disables Defender's test mode. You can use this, or the
+  # configure_defender method to enable the test mode, but you should
+  # probably use this if you only temporarily want to enable the test mode.
+  def self.test_mode=(test_mode)
+    @test_mode = test_mode
+  end
+
+  # Internal: This is for replacing the Defensio backend when running tests.
   def self.defensio=(defensio)
     @defensio = defensio
   end
 
-  ##
-  # The Defensio backend. If no backend has been set yet, this will create one
-  # with the api key set with {Defender.api_key}.
+  # Internal: The Defensio backend. If no backend has been set yet, this will
+  # create one with the API key set with #api_key=.
   #
-  # @return [Defensio] The Defensio backend
+  # Returns the Defensio backend.
   def self.defensio
     return @defensio  if defined?(@defensio)
     require 'defensio'
     @defensio ||= Defensio.new(@api_key, "Defender | #{VERSION} | Henrik Hodne | dvyjones@binaryhex.com")
   end
-
-  ##
-  # Calls a defensio method and wraps in error handling.
-  #
-  # Returns false if the method failed, otherwise returns whatever the method returns
-  #
-  # @param [Symbol] method Which method to call.
-  # @return [false, Array(Fixnum, Hash)]
-  def self.call(method, *args)
-    code, data = defensio.send(method, *args)
-    if code == 200 && data['status'] == 'success'
-      [code, data]
-    else
-      false
-    end
-  end
 end

data/lib/defender/defender_error.rb

@@ -1,5 +1,4 @@
 module Defender
-  ##
   # Defender exception class. This will be thrown on errors returned by
   # Defensio.
   class DefenderError < StandardError

data/lib/defender/spammable.rb

@@ -1,96 +1,94 @@
 module Defender
-  ##
-  # Include this in your ActiveModel-supporting model to enable spam
-  # filtering.
+  # Includes all the model magic for Defender. This module should be included in
+  # your model to enable Defender on it. Defender does some automatic detection
+  # on your setup, but you need to do some configuration yourself. You can set
+  # the API key in two different ways. If you only use Defender on one model,
+  # you can configure the API key in the model with the configure_defender
+  # method. If you prefer to use initializers, or you have multiple models, you
+  # probably want to define it in an initializer. You can do this by calling
+  # Defender.api_key directly, like this:
   #
-  # Defender will try to autodetect details about your rails setup, but you
-  # need to do some configuration yourself. If you already have an application
-  # config file that loads into a constant named APP_CONFIG, and your
-  # comment model has an attribute named 'body', 'content' or 'comment'
-  # including the comment body, then you are almost ready to go. Create the
-  # 'spam' and 'defensio_sig' attribute in the database (a boolean and a
-  # string, respectively) and then include {Defender::Spammable} in your
-  # model. You can now call #spam? on your model after saving it.
-  # Congratulations!
+  #   Defender.api_key = 'This is your API key'
   #
-  # Defender requires the model to have callbacks, more exactly, the
-  # before_save callback. Most ActiveModel-libraries should have that, so you
-  # should only need to worry if you're making your own models. Just look at
-  # {Defender::Test::Comment} for an example comment model.
+  # Defender only requires your models to have a before_save callback, but since
+  # most ActiveModel libraries should have this you only need to worry about it
+  # if you're making your own models. Just have a look at
+  # Defender::Test::Comment for an example comment model.
   module Spammable
-    # These are the default attribute names Defender will pull information
-    # from if no other names are configured. So the content of the comment
-    # will be pulled from 'body', if that attribute exists. Otherwise, it will
-    # pull from 'content'. If that doesn't exist either, it will pull from
-    # 'comment'. If that doesn't exist either, you should configure your own
-    # name in {Defender::Spammable::ClassMethods.configure_defender}.
+    # Public: These are the default attribute names Defender will pull
+    # information from if no other names are configured. So the content of the
+    # comment will be pulled from 'body', if that attribute exists. Otherwise,
+    # it will be pulled from 'content'. If that doesn't exist either, it will
+    # pull from 'comment'. If that attribute doesn't exist either, you should
+    # configure your own attributes with the configure_defender method.
     DEFENSIO_KEYS = {
       'content' => [:body, :content, :comment],
       'author-name' => [:author_name, :author],
       'author-email' => [:author_email, :email],
       'author-ip' => [:author_ip, :ip],
       'author-url' => [:author_url, :url]
-    }
-    
-    ##
-    # These methods will be pulled in as class methods in your model when
-    # including {Defender::Spammable}.
+    }.freeze
+
+    # Public: Methods that will be included as class methods when including
+    # Defender::Spammable into your model.
     module ClassMethods
-      ##
-      # Configure Defender by passing a set of options.
-      #
-      # @param [Hash] options Options for configuring Defender.
-      # @option options [Hash] :keys Mapping between field names in the
-      #   database and in defensio.
-      # @option options [String] :api_key Your Defensio API key. Get one at
-      #   defensio.com.
-      # @option options [Boolean] :test_mode Set Defender in test mode. See
-      #   {#test_mode}.
-      # 
+      # Public: Configures various Defender options.
+      #
+      # options - The hash options used to configure Defender:
+      #           :keys      - A Hash which maps field names in the database to
+      #                        Defensio field names (optional).
+      #           :api_key   - Your Defensio API key String (optional).
+      #           :test_mode - Set this to true to enable the test mode. See
+      #                        Defender.test_mode for more information.
+      #
+      # Examples
+      #
+      #   configure_defender :keys => { 'content' => :comment_content },
+      #     :api_key => 'Your API key.', :test_mode => true
+      #
+      # Returns nothing
       def configure_defender(options)
         keys = options.delete(:keys)
         _defensio_keys.merge!(keys) unless keys.nil?
         api_key = options.delete(:api_key)
         Defender.api_key = api_key unless api_key.nil?
-        self.test_mode = options.delete(:test_mode)
+        Defender.test_mode = options.delete(:test_mode)
       end
-      
-      ##
-      # Set this to true to put Defender in "test mode". When in test mode, you
-      # can check if your code is working properly you can specify in the
-      # content field what kind of response you want. If you want a comment to
-      # be marked as spam with a spaminess of 0.85 you write [spam,0.85]
-      # somewhere in the content field of the document. If you want a malicious
-      # response with a spaminess of 0.99 you write [malicious,0.99] and for an
-      # innocent response you write [innocent,0.25]. This is the preferred way
-      # of testing, if you write spammy comments you might hurt the Defensio
-      # performance.
-      attr_accessor :test_mode
-      
-      ##
-      # Returns the key-attribute mapping used.
-      #
-      # Will automatically set it to the defaults in {DEFENSIO_KEYS} if
-      # nothing else has been set before.
+
+      # Deprecated: Returns whether Defender is in "test mode".
+      #
+      # Use Defender.test_mode instead.
+      def test_mode
+        Defender.test_mode
+      end
+
+      # Deprecated: Enables/disables Defender's test mode.
+      #
+      # Use Defender.test_mode= instead.
+      def test_mode=(test_mode)
+        Defender.test_mode = test_mode
+      end
+
+      # Internal: Returns the key-attribute mapping Hash used.
+      #
+      # This will default to DEFENSIO_KEYS, but can be modified.
+      #
+      # The Public API has access to this through configure_defender.
       def _defensio_keys
         @_defensio_keys ||= DEFENSIO_KEYS.dup
       end
     end
-    
-    ##
-    # These methods will be pulled in as instance methods in your model when
-    # including {Defender::Spammable}.
+
+    # Public: Methods that will be included as instance methods when including
+    # Defender::Spammable into your model.
     module InstanceMethods
-      ##
-      # Returns true if the comment is recognized as spam or malicious.
-      #
-      # If the value is stored in the database that value will be returned.
-      # If nil is returned, the comment has not yet been submitted to
-      # Defensio.
+      # Public: Whether the comment is recognized a malicious comment or as
+      # spam.
       #
-      # @raise [Defender::DefenderError] Raised if there is no spam attribute
-      #   in the model.
-      # @return [Boolean] Whether the comment is spam or not.
+      # Returns the Boolean value stored in the database, or nil if the comment
+      #   hasn't been submitted to Defensio yet.
+      # Raises Defender::DefenderError if there is no spam attribute in the
+      #   model.
       def spam?
         if self.new_record?
           nil
@@ -100,36 +98,80 @@ module Defender
           raise Defender::DefenderError, 'You need to add a spam attribute to the model'
         end
       end
-      
-      ##
-      # Pass in some data to be sent to defensio. You can use this method to
-      # pass in more data that you don't want to save in the model.
+
+      # Public: Report a false positive to Defensio and update the spam
+      # attribute.
+      #
+      # A false positive is a legitimate comment incorrectly marked as spam.
+      #
+      # This must be done within 30 days of the comment originally being
+      # submitted. If you need to update this after that, just set the spam
+      # attribute on your model and save it.
       #
-      # This can be called several times if you want to add more data or
-      # update data already added (using the same key twice will overwrite).
+      # Raises a Defender::DefenderError if Defensio returns an error.
+      def false_positive!
+        document = Defender.defensio.put_document(self.defensio_sig, {'allow' => 'true'}).last
+        if document['status'] == 'failed'
+          raise DefenderError, document['message']
+        end
+        update_attribute(:spam, false)
+      end
+
+      # Public: Report a false negative to Defensio and update the spam
+      # attribute.
       #
-      # Returns the data to be sent. Pass without a parameter to not modify
-      # the data.
+      # A false negative is a spammy comment incorrectly marked as legitimate.
       #
-      # @param [Hash<String => Object>] data The data to send to defensio. See
-      #   the README for the possible key values.
+      # This must be done within 30 days of the comment originally being
+      # submitted. If you need to update this after that, just set the spam
+      # attribute on your model and save it.
+      #
+      # Raises a Defender::DefenderError if Defensio returns an error.
+      def false_negative!
+        document = Defender.defensio.put_document(self.defensio_sig, {'allow' => 'false'}).last
+        if document['status'] == 'failed'
+          raise DefenderError, document['message']
+        end
+        update_attribute(:spam, true)
+      end
+
+      # Public: Pass in more data to be sent to Defensio. You should use this
+      # for data you don't want to save in the model, for instance HTTP headers.
+      #
+      # This can be called several times, the new data will be merged into the
+      # existing data. If you use the same key twice, the new value will
+      # overwrite the old.
+      #
+      # data - The Hash data to send to Defensio. Check the README for the
+      #        possible keys.
+      #
+      # Examples
+      #
+      #   def create # A Rails controller action
+      #     @comment = Comment.new(params[:comment])
+      #     @comment.defensio_data(
+      #       'http-headers' => request.env.map {|k,v| "#{k}: #{v}" }.join("\n")
+      #     )
+      #   end
+      #
+      # Returns the data to be sent.
       def defensio_data(data={})
         @_defensio_data ||= {}
         @_defensio_data.merge!(data)
         @_defensio_data
       end
-      
+
       private
-      
-      ##
-      # The callback that will be run before a document is saved.
+
+      # Internal: The callback that will be run before a document is created..
       #
-      # This will gather all the data and send it off to Defensio, and then
-      # set the spam and defensio_sig attributes (and spaminess if it's
-      # defined) before the model will be saved.
+      # This will gather all the data and send it off to Defensio, and then set
+      # the spam and defensio_sig attributes (and spaminess if it's defined)
+      # before the model will be saved.
       #
-      # @raise Defender::DefenderError If Defensio returns an error.
-      def _defender_before_save
+      # Raises a Defender::DefenderError if Defensio returns an error. Please
+      #   note that this will cancel the save.
+      def _defender_before_create
         data = {}
         _defensio_keys.each do |key, names|
           next if names.nil?
@@ -137,61 +179,60 @@ module Defender
         end
         data.merge!({
           'platform' => 'ruby',
-          'type' => (self.class.test_mode ? 'test' : 'comment')
+          'type' => (Defender.test_mode ? 'test' : 'comment')
         })
         data.merge!(defensio_data) if defined?(@_defensio_data)
-        document = Defender.defensio.post_document(data).last
-        if document['status'] == 'failed'
-          raise DefenderError, document['message']
+        if document = Defender.defensio.post_document(data).last
+          if document['status'] == 'failed'
+            raise DefenderError, document['message']
+          end
+          self.spam = !document['allow']
+          self.defensio_sig = document['signature'].to_s
+          self.spaminess = document['spaminess'] if self.respond_to?(:spaminess=)
+        else
+          raise DefenderError, 'Got nil response from Defensio API, service might be down'
         end
-        self.spam = !document['allow'] 
-        self.defensio_sig = document['signature'].to_s
-        self.spaminess = document['spaminess'] if self.respond_to?(:spaminess=)
+        true
       end
-      
-      ##
-      # Return the first attribute value from a list of attribute names/
+
+      # Internal: Returns value of the first attribute that exists in a list of
+      # attributes.
       #
-      # @param [Array<Symbol>, Symbol] names A list of attribute names
-      # @return [] The attribute value of the first existing attribute
-      # @return [nil] If no attribute was found (or if attribute value is nil)
+      # names - A Symbol or Array of Symbols representing the attribute name(s).
       def _pick_attribute(names)
         [names].flatten.each do |name|
           return self.send(name) if self.respond_to?(name)
         end
         return nil
       end
-      
-      ##
-      # Retrieves the Defensio document from the server if it hasn't been
-      # retrieved before or if the first parameter is true.
-      #
-      # @param [Boolean] force Pass true to force a refetch, otherwise it will
-      #   get the cached document (if one is cached).
-      # @return [Hash] The document retrieved from the server.
+
+      # Internal: Retrieves the Defensio document from the server if it hasn't
+      # been retrieved before or if the first parameter is true.
+      #
+      # force - A Boolean representing whether to force a refetch. If a refetch
+      #         isn't forced, the document will only be fetched if it hasn't
+      #         been fetched already.
+      #
+      # Returns the Hash with the information retrieved from the server.
       def _get_defensio_document(force=false)
-        if force || @_defensio_document.nil?
+        if force || !defined?(@_defensio_document) || @_defensio_document.nil?
           @_defensio_document = Defender.defensio.get_document(self.defensio_sig).last
         end
         @_defensio_document
       end
-      
-      ##
-      # Wrapper for {Defender::Spammable::ClassMethods._defensio_keys}.
-      #
-      # @see Defender::Spammable::ClassMethods._defensio_keys
+
+      # Internal: Wrapper for the class method with the same name.
       def _defensio_keys
         self.class._defensio_keys
       end
     end
-    
-    ##
-    # Includes {Defender::Spammable::ClassMethods} and
-    # {Defender::Spammable::InstanceMethods} and sets up save callback.
+
+    # Internal: Includes the ClassMethods and InstanceMethods and sets up the
+    # before_save callback.
     def self.included(receiver)
       receiver.extend         ClassMethods
       receiver.send :include, InstanceMethods
-      receiver.send :before_save, :_defender_before_save
+      receiver.send :before_create, :_defender_before_create
     end
   end
-end
+end

data/lib/defender/test/comment.rb

@@ -1,36 +1,48 @@
 require 'active_model'
 
-##
 # Stuff to test Defender. You probably shouldn't use this in your application,
 # but it is included as an example of the minimum needed for a valid setup.
 module Defender::Test
-  ##
   # A fake Comment class to use. No need to require ActiveRecord and set up an
   # actual database. We will use ActiveModel for callbacks though.
   class Comment
     extend ActiveModel::Naming
     extend ActiveModel::Callbacks
     define_model_callbacks :save
-  
+    define_model_callbacks :create
+
     # We now have a "valid" model, let's bring in Defender.
     include Defender::Spammable
-  
+
     attr_accessor :body, :author, :author_ip, :created_at, :spam, :defensio_sig
-  
-    ##
+
     # Returns true if save has been called, false otherwise.
     def new_record?
-      !@saved ||= false
+      !(@saved ||= false)
     end
-  
-    ##
+
     # Run save callback and make {Defender::Test::Comment.new_record?} return false.
-    def save
-      _run_save_callbacks do
-        # We're not actually saving anything, just letting Defender know we
-        # would be.
+    #
+    # The with_callbacks method is only for using this as a test interface.
+    def save(with_callbacks=true)
+      if with_callbacks
+        _run_save_callbacks do
+          # We're not actually saving anything, just letting Defender know we
+          # would be.
+          unless defined?(@saved) && @saved
+            _run_create_callbacks do
+              @saved = true
+            end
+          end
+        end
+      else
         @saved = true
       end
     end
+
+    def update_attribute(name, value)
+      self.send("#{name}=".to_sym, value)
+      self.save
+    end
   end
-end
+end

data/lib/defender/version.rb

@@ -1,4 +1,4 @@
 module Defender
   # Current Defender version
-  VERSION = '2.0.2'
+  VERSION = '2.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: defender
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,12 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-02 00:00:00.000000000 +02:00
-default_executable: 
+date: 2012-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: defensio
-  requirement: &2153287360 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,10 +21,15 @@ dependencies:
         version: 0.9.1
   type: :runtime
   prerelease: false
-  version_requirements: *2153287360
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.1
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &2153286860 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +37,15 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2153286860
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2153286480 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +53,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153286480
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2153285640 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,7 +69,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153285640
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - dvyjones@dvyjones.com
@@ -68,7 +87,6 @@ files:
 - lib/defender/test/comment.rb
 - lib/defender/version.rb
 - lib/defender.rb
-has_rdoc: true
 homepage: 
 licenses: []
 post_install_message: 
@@ -83,7 +101,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2741349701634154017
+      hash: -4330272566146055507
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -92,10 +110,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2741349701634154017
+      hash: -4330272566146055507
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.21
 signing_key: 
 specification_version: 3
 summary: ActiveModel plugin for Defensio.