ruby-akismet 0.9.3 → 1.0.0

data/README.rdoc

@@ -1,9 +1,9 @@
-Akismet compatible library for checking spams.
+Ruby library for the Akismet anti-spam service.
 
 = Usage
 
 First you need an Akismet (or Typepad Antispam) API key. Then you need
-to setup a few configuration variable:
+to setup a few configuration variables:
 
   Akismet.key  = '123456789'
   Akismet.blog = 'http://example.com'
@@ -12,37 +12,61 @@ To use Typepad Antispam, just specify the host:
 
   Akismet.host = 'api.antispam.typepad.com'
 
-Then you need to call any of the methods with a few attributes,
-and possibly an <code>ActionDispatch::Request</code> object.
+Then you need to call any of the methods with a few attributes, and possibly
+an ActionDispatch::Request object.
 
-= Documentation
+== Documentation
+
+Check rubydoc.info:
 
 http://rubydoc.info/github/ysbaddaden/ruby-akismet/master/frames
 
+Or generate your own:
+
+  ~/src/ruby-akismet$ rake rdoc
+
 = Integrate with Ruby on Rails
 
-On rails 3, add this gem to your <code>Gemfile</code>:
+ruby-akismet integrates nicely with Ruby on Rails, but isn't tied to it except
+for the ActionDispatch::Request object, which isn't required. It should be
+easily integratable with your favorite framework like Sinatra and Merb.
+
+== Rails 3
+
+Add this gem to your Gemfile:
 
   gem 'ruby-akismet', :require => 'akismet'
 
-On rails 2, first install the gem:
+== Rails 2
+
+First install the gem:
 
   gem install ruby-akismet
 
-Then add the gem to your app:
+Then add it to your app:
 
   config.gem 'ruby-akismet', :lib => 'akismet'
 
-Create an initializer file like <code>config/initializers/akismet.rb</code>
+== Configuration
+
+Create an initializer file like <tt>config/initializers/akismet.rb</tt>
 with your configuration:
 
-  Akismet.key  = '123456789'
-  Akismet.blog = 'http://example.com'
+  Akismet.key    = '123456789'
+  Akismet.blog   = 'http://example.com'
+  Akismet.logger = Rails.logger
+
+== Usage
 
-Then in your controller call the appropriate methods (rails 3 example):
+ruby-akismet is meant to be used on the controller side and not on the model
+side, because the Akismet API requires some data that's only available from
+the HTTP request --like the user and proxy IP, referer, etc.
+
+Here is a Rails 3 example:
 
   class CommentsController < ApplicationController
     before_filter :set_post
+    
     respond_to :html, :xml
     
     def create
@@ -84,6 +108,8 @@ Then in your controller call the appropriate methods (rails 3 example):
 
 = Author
 
+- Julien Portalier <ysbaddaden@gmail.com>
+
 ruby-akismet is a complete rewrite of Akismetor by Ryan Bates and
 Levy Carneiro Jr. that you can find at http://github.com/levycarneiro/akismetor
 

data/lib/akismet.rb

@@ -1,46 +1,91 @@
 require 'net/http'
 
 # Akismet compatible library for checking spams.
+# 
+# Before calling any method, you must configure a blog (your website
+# homepage) and your Akismet or Typepad Antispam API key.
+# 
+#   Akismet.key  = '123456789'
+#   Akismet.blog = 'http://example.com'
+# 
 class Akismet
-  VERSION     = '0.9.3'.freeze
-  API_VERSION = '1.1'.freeze
+  # Raised whenever a command is issued but the API key hasn't been configured.
+  class MissingKey < StandardError
+  end
 
-  @@host = 'rest.akismet.com'
-  @@key  = nil
-  @@blog = nil
-  @@extra_headers = [
-    'HTTP_REMOTE_ADDR',
-    'HTTP_CLIENT_IP',
-    'HTTP_X_FORWARDED_FOR',
-    'HTTP_CONNECTION'
-  ]
+  VERSION     = '1.0.0'.freeze
+  API_VERSION = '1.1'.freeze
 
   class << self
-    # Configure an alternate API server.
+    # Configure an alternate API host server (defaults to
+    # <tt>'rest.akismet.com'</tt>).
     def host=(host)
       @@host = host
     end
 
+    def host
+      @@host
+    end
+
     # Configure your API key (required).
     def key=(key)
       @@key = key
     end
 
-    # Configure your homepage URL (optional).
+    def key
+      @@key
+    end
+
+    # Configure your homepage URL (required).
     def blog=(blog)
       @@blog = blog
     end
 
-    # Configure an array of extra HTTP headers to pass to Akismet from
-    # the request.
+    def blog
+      @@blog
+    end
+
+    def logger=(logger)
+      @@logger = logger
+    end
+
+    def logger
+      @@logger
+    end
+
+    # Configure an Array of extra HTTP headers to pass to the Akismet server
+    # to extract from the request object.
+    # 
+    # Defaults to:
+    # 
+    #   [
+    #     'HTTP_REMOTE_ADDR',
+    #     'HTTP_CLIENT_IP',
+    #     'HTTP_X_FORWARDED_FOR',
+    #     'HTTP_CONNECTION'
+    #   ]
     # 
-    # Example:
+    # Examples:
+    # 
+    #   # replaces the actual list:
+    #   Akismet.extra_headers = ['HTTP_REMOTE_ADDR']
+    #   
+    #   # appends a header to the list:
+    #   Akismet.extra_headers << 'HTTP_ACCEPT_CHARSET'
+    #   
+    #   # appends multiple headers to the list:
+    #   Akismet.extra_headers << ['HTTP_ACCEPT_CHARSET', 'HTTP_ACCEPT_LANGUAGE']
     # 
-    #   Akismet.extra_headers = ['HTTP_REMOTE_ADDR', 'HTTP_CLIENT_IP', 'HTTP_X_FORWARDED_FOR']
     def extra_headers=(headers)
       @@extra_headers = headers
     end
 
+    def extra_headers
+      @@extra_headers.flatten!
+      @@extra_headers.uniq!
+      @@extra_headers
+    end
+
     # Checks if a key is valid or not.
     def valid_key?(key)
       call('verify-key', :key => key) == "valid"
@@ -50,18 +95,25 @@ class Akismet
     # 
     # Required attributes:
     # 
-    # - <code>:permalink</code>
-    # - <code>:comment_author</code>
-    # - <code>:comment_author_url</code>
-    # - <code>:comment_author_email</code>
-    # - <code>:comment_content</code>
+    # - <tt>:permalink</tt>
+    # - <tt>:comment_author</tt>
+    # - <tt>:comment_author_url</tt>
+    # - <tt>:comment_author_email</tt>
+    # - <tt>:comment_content</tt>
+    # 
+    # Those are also required, but will be extracted from the
+    # +request+ object if available:
     # 
-    # Those are also required, but will be extracted from the request object:
+    # - <tt>:user_ip</tt>
+    # - <tt>:user_agent</tt>
+    # - <tt>:referrer</tt> (check spelling!)
     # 
-    # - <code>:user_ip</code>
-    # - <code>:user_agent</code>
-    # - <code>:referer</code>
-    # - plus any more relevant HTTP header.
+    # Plus more relevant HTTP headers from extra_headers.
+    # 
+    # Note that request is supposed to be an instance of
+    # ActionDispatch::Request or ActionController::Request. If not, the object
+    # must respond to +remote_ip+ (IP as string) and +headers+
+    # (an array of HTTP headers).
     # 
     def spam?(attributes, request = nil)
       call('comment-check', attributes, request) == "true"
@@ -79,7 +131,7 @@ class Akismet
     end
 
     # Submits a false-positive comment as non-spam to Akismet.
-    # Takes the same attributes than +spam+.
+    # Takes the same attributes than spam?.
     def submit_ham(attributes)
       call('submit-ham', attributes)
     end
@@ -90,6 +142,17 @@ class Akismet
       end
   end
 
+  self.host   = 'rest.akismet.com'
+  self.key    = nil
+  self.blog   = nil
+  self.logger = nil
+  self.extra_headers = [
+    'HTTP_REMOTE_ADDR',
+    'HTTP_CLIENT_IP',
+    'HTTP_X_FORWARDED_FOR',
+    'HTTP_CONNECTION'
+  ]
+
   def initialize(command, attributes, request = nil)
     @command    = command
     @attributes = attributes
@@ -97,13 +160,15 @@ class Akismet
   end
 
   def call
+    self.class.logger.debug { "  AKISMET  #{@command} #{post_attributes}" } if self.class.logger
+    
     http = Net::HTTP.new(http_host, 80)
     http.post(http_path, post_attributes, http_headers).body
   end
 
   private
     def attributes
-      @attributes[:blog] ||= @@blog
+      @attributes[:blog] ||= self.class.blog
       
       unless @command == 'verify-key'
         @attributes[:comment_type] ||= 'comment'
@@ -112,7 +177,10 @@ class Akismet
           @attributes[:user_ip]    = @request.remote_ip
           @attributes[:user_agent] = @request.headers["HTTP_USER_AGENT"]
           @attributes[:referrer]   = @request.headers["HTTP_REFERER"]
-          @@extra_headers.each { |h| @attributes[h] = @request.headers[h] }
+          
+          self.class.extra_headers.each do |h|
+            @attributes[h] = @request.headers[h]
+          end
         end
       end
       
@@ -133,9 +201,10 @@ class Akismet
 
     def http_host
       unless @command == 'verify-key'
-        "#{@@key}.#{@@host}"
+        raise MissingKey.new("Required Akismet.key is nil.") unless self.class.key
+        "#{self.class.key}.#{self.class.host}"
       else
-        "#{@@host}"
+        "#{self.class.host}"
       end
     end
 

data/test/akismet_test.rb

@@ -1,60 +1,129 @@
 require 'test/unit'
+require 'logger'
+
+require 'rubygems'
+gem 'actionpack'
+gem 'rack'
+require 'action_dispatch'
+
 require File.expand_path("../../lib/akismet.rb", __FILE__)
 
-# TODO: Test with an ActionDispatch::TestRequest object.
 class AkismetTest < Test::Unit::TestCase
   def setup
     Akismet.host = 'api.antispam.typepad.com'
     Akismet.key  = '123456789'
     Akismet.blog = 'http://www.example.com/'
-  end
-
-  def valid_attributes
-    {
-      :user_ip              => '127.0.0.1',
-      :user_agent           => 'Mozilla/5.0 (Macintosh; U; PPC Mac OS X 10.5; en-US; rv:1.9.0.3) Gecko/2008092414 Firefox/3.0.3',
-      :referrer             => 'http://www.example.com/posts',
-      :permalink            => 'http://www.example.com/posts/1',
-      :comment_author       => 'Julien Portalier',
-      :comment_author_url   => 'http://ysbaddaden.wordpress.com/',
-      :comment_author_email => 'julien@example.com',
-      :comment_content      => 'this is a normal comment',
-    }
-  end
-
-  def invalid_attributes
-    invalid = valid_attributes.dup
-    invalid[:comment_author] = 'viagra-test-123'
-    invalid
+    
+    Akismet.logger = Logger.new(File.expand_path("../test.log", __FILE__))
+    Akismet.logger.level = Logger::DEBUG
   end
 
   def test_valid_key
-    assert Akismet.valid_key?('123456789')
+    assert Akismet.valid_key?(Akismet.key)
   end
 
 #  def test_invalid_key
 #    assert !Akismet.valid_key?('abc123')
 #  end
 
+  def test_should_not_fail_with_no_logger
+    Akismet.logger = nil
+    assert Akismet.valid_key?(Akismet.key)
+  end
+
+  def test_should_raise_missing_key
+    Akismet.key = nil
+    assert_raise(Akismet::MissingKey) { Akismet.spam?(full_spam_attributes) }
+  end
+
+  def test_should_not_raise_missing_key_for_valid_key
+    Akismet.key = nil
+    assert_nothing_raised { Akismet.valid_key?('123456789') }
+  end
+
+  def test_extra_headers
+    Akismet.extra_headers = ['HTTP_REMOTE_ADDR']
+    assert_equal ['HTTP_REMOTE_ADDR'], Akismet.extra_headers
+    
+    Akismet.extra_headers << 'HTTP_CLIENT_IP'
+    assert_equal ['HTTP_REMOTE_ADDR', 'HTTP_CLIENT_IP'], Akismet.extra_headers
+    
+    Akismet.extra_headers << ['HTTP_X_FORWARDED_FOR', 'HTTP_CONNECTION']
+    assert_equal ['HTTP_REMOTE_ADDR', 'HTTP_CLIENT_IP', 'HTTP_X_FORWARDED_FOR', 'HTTP_CONNECTION'],
+      Akismet.extra_headers
+  end
+
+  def test_spam_with_actiondispatch_request
+    assert Akismet.spam?(spam_attributes, actiondispatch_request)
+  end
+
+  def test_ham_with_actiondispatch_request
+    assert !Akismet.spam?(ham_attributes, actiondispatch_request)
+  end
+
   def test_spam
-    assert Akismet.spam?(invalid_attributes)
+    assert Akismet.spam?(full_spam_attributes)
   end
 
   def test_not_spam
-    assert !Akismet.spam?(valid_attributes)
+    assert !Akismet.spam?(full_ham_attributes)
   end
 
   def test_ham
-    assert Akismet.ham?(valid_attributes)
+    assert Akismet.ham?(full_ham_attributes)
   end
 
   def test_not_ham
-    assert !Akismet.ham?(invalid_attributes)
+    assert !Akismet.ham?(full_spam_attributes)
   end
 
   def test_submit_spam
+    assert Akismet.submit_spam(spam_attributes)
   end
 
   def test_submit_ham
+    assert Akismet.submit_ham(ham_attributes)
   end
+
+  protected
+    def ham_attributes
+      {
+        :permalink            => 'http://www.example.com/posts/1',
+        :comment_author       => 'Julien Portalier',
+        :comment_author_url   => 'http://ysbaddaden.wordpress.com/',
+        :comment_author_email => 'julien@example.com',
+        :comment_content      => 'this is a normal comment'
+      }
+    end
+
+    def spam_attributes
+      ham_attributes.merge(:comment_author => 'viagra-test-123')
+    end
+
+    def additional_attributes
+      {
+        :user_ip    => '127.0.0.1',
+        :user_agent => 'Mozilla/5.0 (X11; U; Linux i686; fr-FR) AppleWebKit/534.7 (KHTML, like Gecko) Ubuntu/10.04 Chromium/7.0.517.41 Chrome/7.0.517.41 Safari/534.7',
+        :referrer   => 'http://www.example.com/posts'
+      }
+    end
+
+    def full_spam_attributes
+      spam_attributes.merge(additional_attributes)
+    end
+
+    def full_ham_attributes
+      ham_attributes.merge(additional_attributes)
+    end
+
+    def actiondispatch_request
+      request = ActionDispatch::TestRequest.new(
+        'HTTP_REFERER'     => 'http://www.example.com/posts/1',
+        'HTTP_REMOTE_ADDR' => '127.0.0.1',
+        'HTTP_USER_AGENT'  => 'Mozilla/5.0 (X11; U; Linux i686; fr-FR) AppleWebKit/534.7 (KHTML, like Gecko) Ubuntu/10.04 Chromium/7.0.517.41 Chrome/7.0.517.41 Safari/534.7',
+        'HTTP_CONNECTION'  => 'close'
+      )
+      request.remote_addr = '127.0.0.1'
+      request
+    end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-akismet
 version: !ruby/object:Gem::Version 
-  hash: 61
+  hash: 23
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 9
-  - 3
-  version: 0.9.3
+  - 0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Julien Portalier
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-23 00:00:00 +02:00
+date: 2010-10-24 00:00:00 +02:00
 default_executable: 
 dependencies: []