akismet 0.1.2 → 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Jonah Burke
+
+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,68 @@
+Akismet
+=======
+
+A Ruby client for the Akismet API.
+
+Instantiate an `Akismet::Client` with your API key and home page URL. Then
+call `verify_key`, `check_comment`, `submit_ham`, or `submit_spam`.
+
+Use `Akismet::Client.open` or `Akismet::Client#open` to submit multiple
+requests over a single TCP connection.
+
+See lib/akismet/client.rb for more documentation or generate docs with YARD. 
+
+Verify an API key
+-----------------
+
+    Akismet::Client.new( 'apikey123', 'http://jonahb.com' ).verify_key
+
+
+Check whether a comment is spam
+-------------------------------
+
+    client = Akismet::Client.new( 'apikey123',
+      'http://jonahb.com',
+      :app_name => 'jonahb.com',
+      :app_version => '1.0' )
+
+    # assumes variables comment, post_url, request (a racklike HTTP request)
+    spam = client.comment_check( request.remote_ip,
+      request.user_agent,
+      :content_type => 'comment',
+      :referrer => request.headers[ 'HTTP_REFERER' ],
+      :permalink => post_url, 
+      :comment_author => comment.author,
+      :comment_author_email => comment.author_email,
+      :comment_content => comment.body )
+
+    if spam
+      # ...
+    end 
+
+Submit a batch of checks using a single TCP connection
+------------------------------------------------------
+
+    client = Akismet::Client.new( 'apikey123',
+      'http://jonahb.com',
+      :app_name => 'jonahb.com',
+      :app_version => '1.0' )
+
+    begin
+      client.open
+      comments.each do |comment|
+        client.comment_check( ... )  # see example above
+      end
+    ensure
+      client.close
+    end
+
+    # ... or ...
+
+    Akismet::Client.open( 'apikey123',
+      'http://jonahb.com',
+      :app_name => 'jonahb.com',
+      :app_version => '1.0' ) do |client|
+      comments.each do |comment|
+        client.comment_check( ... )  # see example above
+      end
+    end

data/lib/akismet.rb

@@ -1,12 +1,7 @@
-require File.dirname( __FILE__ ) + '/akismet/version'
-require File.dirname( __FILE__ ) + '/akismet/service'
-require File.dirname( __FILE__ ) + '/akismet/client'
-
-module Akismet
-
-  # convenience method
-  def self.verify_key( api_key, home_url )
-    Service.new.verify_key api_key, home_url
-  end
-
+%w{
+  version
+  error
+  client
+}.each do |file|
+  require File.join( File.dirname( __FILE__ ), 'akismet', file )
 end

data/lib/akismet/client.rb

@@ -1,41 +1,410 @@
+require 'net/http'
+require 'cgi'
+
 module Akismet
+
+  # A Ruby client for the Akismet API.
+  #
+  # @example
+  #
+  #   # Verify an API key
+  #   #
+  # 
+  #   Akismet::Client.new( 'apikey123', 'http://jonahb.com' ).verify_key
+  #
+  # @example
+  #
+  #   # Check whether a comment is spam
+  #   #
+  #
+  #   client = Akismet::Client.new( 'apikey123',
+  #     'http://jonahb.com',
+  #     :app_name => 'jonahb.com',
+  #     :app_version => '1.0' )
+  #
+  #   # assumes variables comment, post_url, request (a racklike HTTP request)
+  #   spam = client.comment_check( request.remote_ip,
+  #     request.user_agent,
+  #     :content_type => 'comment',
+  #     :referrer => request.headers[ 'HTTP_REFERER' ],
+  #     :permalink => post_url, 
+  #     :comment_author => comment.author,
+  #     :comment_author_email => comment.author_email,
+  #     :comment_content => comment.body )
+  #
+  #   if spam
+  #     # ...
+  #   end 
+  #
+  # @example
+  #
+  #   # Submit a batch of checks using a single TCP connection
+  #   #
+  #
+  #
+  #   client = Akismet::Client.new( 'apikey123',
+  #     'http://jonahb.com',
+  #     :app_name => 'jonahb.com',
+  #     :app_version => '1.0' )
+  #
+  #   begin
+  #     client.open
+  #     comments.each do |comment|
+  #       client.comment_check( ... )  # see example above
+  #     end
+  #   ensure
+  #     client.close
+  #   end
+  #
+  #   # ... or ...
+  #
+  #   Akismet::Client.open( 'apikey123',
+  #     'http://jonahb.com',
+  #     :app_name => 'jonahb.com',
+  #     :app_version => '1.0' ) do |client|
+  #     comments.each do |comment|
+  #       client.comment_check( ... )  # see example above
+  #     end
+  #   end
+  #
+  #
   class Client
 
-    attr_accessor :api_key, :home_url
+    # The API key obtained at akismet.com.
+    # @return [String]
+    #
+    attr_reader :api_key
+
+
+    # The URL of the home page of the application making the request.
+    # @return [String]
+    #
+    attr_reader :home_url
+
+
+    # The name of the application making the request, e.g "jonahb.com".
+    # @return [String]
+    #
+    attr_reader :app_name
+
+
+    # The version of the application making the request, e.g. "1.0".
+    # @return [String]
+    #
+    attr_reader :app_version
 
-    def initialize( api_key, home_url )
+
+    # @param [String] api_key
+    #   The API key obtained at akismet.com.
+    # @param [String] home_url
+    #   The URL of the home page of the application making the request.
+    # @option options [String] :app_name
+    #   The name of the application making the request, e.g. "jonahb.com".
+    #   Forms part of the User-Agent header submitted to Akismet.
+    # @option options [String] :app_version
+    #   The version of the application making the request, e.g. "1.0". Forms
+    #   part of the User-Agent header submitted to Akismet. Ignored if
+    #   :app_name is not privded.
+    #
+    def initialize( api_key, home_url, options = {} )
       @api_key = api_key
       @home_url = home_url
-      @service = Service.new
+      @app_name = options[ :app_name ]
+      @app_version = options[ :app_version ]
+    end
+
+
+    # Yields a new open Client, closing the Client when the block returns.
+    # Takes the same arguments as {#initialize}. Use for submitting a batch of
+    # requests using a single TCP and HTTP session.
+    #
+    # @yield [Akismet::Client]
+    # @return [nil]
+    # @see #initialize
+    # @see #open
+    #
+    def self.open( api_key, home_url, options = {} )
+      raise "Block required" unless block_given?
+      client = nil
+      begin
+        client = new( api_key, home_url, options )
+        client.open
+        yield client
+      ensure
+        client.close if client
+      end
+      nil
+    end
+
+
+    # Opens the client. You may use this method in combination with {#close}
+    # to submit a batch of requests using a single TCP and HTTP session.
+    #
+    # If you don't call this before calling {#comment_check}, {#submit_ham},
+    # or {#submit_spam}, a session will be created and opened for the duration 
+    # of the call.
+    #
+    # Note that calls to {#verify_key} always create a session. This is due to
+    # a peculiarity of the Akismet API where {#verify_key} requests must be
+    # sent to a different host.
+    #
+    # @return [self]
+    # @raise [RuntimeError]
+    #   The client is already open.
+    # @see #close
+    # @see Akismet::Client.open
+    #
+    def open
+      raise "Already open" if open?
+      @http_session = Net::HTTP.new( "#{ api_key }.rest.akismet.com", 80 )
+      @http_session.start
+      self
+    end
+
+
+    # Closes the Client.
+    # @return [self]
+    # @see #open
+    #
+    def close
+      @http_session.finish if open?
+      @http_session = nil
+      self
+    end
+
+
+    # Whether the Client is open.
+    # @return [boolean]
+    #
+    def open?
+      @http_session && @http_session.started?
     end
 
+
+    # Checks the validity of the API key.
+    # @return [boolean]
+    #
     def verify_key
-      @service.verify_key @api_key, @home_url
+      response = Net::HTTP.start( 'rest.akismet.com', 80 ) do |session|
+        invoke( session, 'verify-key', :blog => home_url, :key => api_key )
+      end
+
+      unless %w{ valid invalid }.include?( response.body )
+        raise_with_response response
+      end
+
+      response.body == 'valid'
     end
 
-    def check( user_ip, user_agent, params = {} )
-      @service.comment_check @api_key,
-        @home_url,
+
+    # Checks whether a comment is spam. You are encouraged the submit, in
+    # addition to the documented parameters, data about the client and the
+    # comment submission. For example, if the client is an HTTP server,
+    # include HTTP headers and environment variables.
+    #
+    # If the Client is not open, opens it for the duration of the call.
+    #
+    # @return [boolean]
+    # @raise [Akismet::Error]
+    # @param [String] user_ip
+    #   The IP address of the submitter of the comment.
+    # @param [String] user_agent
+    #   The user agent of the web browser submitting the comment. Typically
+    #   the HTTP_USER_AGENT CGI variable. Not to be confused with the user
+    #   agent of the Akismet library.
+    # @option params [String] :referrer
+    #   The value of the HTTP_REFERER header. Note that the parameter is
+    #   spelled with two consecutive 'r's.
+    # @option params [String] :permalink
+    #   The permanent URL of the entry to which the comment pertains.
+    # @option params [String] :comment_type
+    #   'comment', 'trackback', 'pingback', or a made-up value like
+    #   'registration'
+    # @option params [String] :comment_author
+    #   The name of the author of the comment.
+    # @option params [String] :comment_author_email
+    #   The email address of the author of the comment.
+    # @option params [String] :comment_author_url
+    #   A URL submitted with the comment.
+    # @option params [String] :comment_content
+    #   The text of the comment.
+    #
+    def comment_check( user_ip, user_agent, params = {} )
+      response = invoke_comment_method( 'comment-check',
         user_ip,
         user_agent,
-        params
+        params )
+
+      unless %w{ true false }.include?( response.body )
+        raise_with_response response
+      end
+
+      response.body == 'true'
     end
 
-    def ham( user_ip, user_agent, params = {} )
-      @service.submit_ham @api_key,
-        @home_url,
+
+    # Submits a comment that has been identified as not-spam (ham). Takes
+    # the same arguments as {#comment_check}. If the Client is not open, opens
+    # it for the duration of the call.
+    #
+    # @return [nil]
+    # @raise [Akismet::Error]
+    # @see #comment_check
+    #
+    def submit_ham( user_ip, user_agent, params = {} )
+      response = invoke_comment_method( 'submit-ham',
         user_ip,
         user_agent,
-        params
+        params )
+
+      unless response.body == 'Thanks for making the web a better place.'
+        raise_from_response response
+      end
+
+      nil
     end
 
-    def spam( user_ip, user_agent, params = {} )
-      @service.submit_spam @api_key,
-        @home_url,
+
+    # Submits a comment that has been identified as spam. Takes the same
+    # arguments as {#comment_check}. If the Client is not open, opens it for
+    # the duration of the call.
+    #
+    # @return [nil]
+    # @raise [Akismet::Error]
+    # @see #comment_check
+    #
+    def submit_spam( user_ip, user_agent, params = {} )
+      response = invoke_comment_method( 'submit-spam',
         user_ip,
         user_agent,
-        params
+        params )
+
+      unless response.body == 'Thanks for making the web a better place.'
+        raise_from_response response
+      end
+
+      nil
+    end
+
+
+  private
+
+
+    # Yields an HTTP session to the given block. Uses this instance's open
+    # session if any; otherwise opens one and closes it when the block
+    # returns.
+    # @yield [Net::HTTP]
+    #
+    def in_http_session
+      raise "Block required" unless block_given?
+      if open?
+        yield @http_session
+      else
+        begin
+          open
+          yield @http_session
+        ensure
+          close
+        end
+      end
+    end
+
+
+    # Raises an error given a response. The Akismet documentation states that
+    # the HTTP headers of the response may contain error strings. I can't
+    # seem to find them, so for now just raise an unknown error.
+    # @param [Net::HTTPResponse] response
+    #
+    def raise_with_response( response )
+      raise Error.new( Error::UNKNOWN, 'Unknown error' )
+    end
+
+
+    # @param [String] method_name
+    # @param [String] user_ip
+    # @param [String] user_agent
+    # @param [Hash] params
+    # @return [Net::HTTPResponse]
+    # @raise [Akismet::Error]
+    #   The API key is invalid.
+    #
+    def invoke_comment_method( method_name, user_ip, user_agent, params = {} )
+      params = params.merge :blog => home_url,
+        :user_ip => user_ip,
+        :user_agent => user_agent
+      
+      response = in_http_session do |session|
+        invoke( session, method_name, params )
+      end
+
+      if response.body == 'invalid'
+        raise Error.new( Error::INVALID_API_KEY, 'Invalid API key' )
+        raise Error, 'Invalid API key'
+      end
+
+      response
+    end
+
+
+    # @param [Net::HTTP] http_session
+    #   A started HTTP session
+    # @param [String] method_name
+    # @return [Net::HTTPResponse]
+    # @raise [Akismet::Error]
+    #   An HTTP response other than 200 is received.
+    #
+    def invoke( http_session, method_name, params = {} )
+      response = http_session.post( "/1.1/#{ method_name }",
+        url_encode( params ),
+        http_headers )
+
+      unless response.is_a?( Net::HTTPOK )
+        raise Error, "HTTP #{ response.code } received (expected 200)"
+      end
+
+      response
+    end
+
+
+    # @return [Hash]
+    #
+    def http_headers
+      { 'User-Agent' => user_agent }
+    end
+
+
+    # @return [String]
+    #
+    def url_encode( hash = {} )
+      hash.collect do |k, v|
+        "#{ CGI.escape( k.to_s ) }=#{ CGI.escape( v.to_s ) }"
+      end.join( "&" )
+    end
+
+
+    # From the Akismet documentation:
+    #   If possible, your user agent string should always use the following
+    #   format: Application Name/Version | Plugin Name/Version
+    # @return [String]
+    #
+    def user_agent
+      [ user_agent_app, user_agent_plugin ].compact.join( " | " )
     end
 
+
+    # Returns nil if the Client was instantiated without an app_name.
+    # @return [String]
+    #
+    def user_agent_app
+      app_name && [ app_name, app_version ].compact.join( "/" )
+    end
+
+
+    # @return [String]
+    #
+    def user_agent_plugin
+      "Ruby Akismet/#{ Akismet::VERSION }"
+    end  
+  
   end
-end
+end

data/lib/akismet/error.rb

@@ -0,0 +1,23 @@
+module Akismet
+
+  class Error < StandardError
+
+    UNKNOWN = 1
+    INVALID_API_KEY = 2
+
+    # An error code corresponding to a constant in Akismet::Error.
+    # @return [Integer]
+    attr_reader :code
+
+    # @param [String] message
+    #   A human-readable description of the error.
+    # @param [Integer] code
+    #   An error code corresponding to a constant in Akismet::Error.
+    #
+    def initialize( code, message = nil )
+      super( message )
+      @code = code
+    end
+  end
+
+end

data/lib/akismet/version.rb

@@ -1,3 +1,7 @@
 module Akismet
-  VERSION = '0.1.2'
+  # The version of the Akismet gem.
+  VERSION = '1.0.0'
+
+  # The supported version of the Akismet API.
+  API_VERSION = '1.3'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: akismet
 version: !ruby/object:Gem::Version 
-  hash: 31
-  prerelease: false
+  hash: 23
+  prerelease: 
   segments: 
-  - 0
   - 1
-  - 2
-  version: 0.1.2
+  - 0
+  - 0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Jonah Burke
@@ -15,13 +15,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-01 00:00:00 -05:00
-default_executable: 
+date: 2012-01-14 00:00:00 Z
 dependencies: []
 
 description: A Ruby client for the Akismet API
-email: 
-- jonah@bigthink.com
+email: jonah@jonahb.com
 executables: []
 
 extensions: []
@@ -29,14 +27,15 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- README.md
+- MIT-LICENSE
 - lib/akismet/client.rb
-- lib/akismet/service.rb
+- lib/akismet/error.rb
 - lib/akismet/version.rb
 - lib/akismet.rb
-has_rdoc: true
-homepage: http://github.com/bigthink/akismet
-licenses: []
-
+homepage: http://github.com/jonahb/akismet
+licenses: 
+- MIT
 post_install_message: 
 rdoc_options: []
 
@@ -45,31 +44,28 @@ require_paths:
 required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ~>
+  - - ">="
     - !ruby/object:Gem::Version 
-      hash: 59
+      hash: 3
       segments: 
-      - 1
-      - 8
-      - 6
-      version: 1.8.6
+      - 0
+      version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 17
+      hash: 3
       segments: 
-      - 1
-      - 3
-      - 5
-      version: 1.3.5
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.12
 signing_key: 
 specification_version: 3
 summary: A Ruby client for the Akismet API
 test_files: []
 
+has_rdoc: yard

data/lib/akismet/service.rb

@@ -1,87 +0,0 @@
-require 'net/http'
-require 'cgi'
-
-module Akismet
-
-  AKISMET_VERSION = 1.1
-  PORT = 80
-  HEADERS = { 'User-Agent' => "Ruby/Akismet #{ VERSION }" }
-
-  module CommentType
-    COMMENT = 'comment'
-    TRACKBACK = 'trackback'
-    PINGBACK = 'pingback'
-  end
-
-  # Parameters to +comment_check+, +submit_ham+, and +submit_spam+ may
-  # include:
-  #
-  # * content_type
-  # * comment_author
-  # * comment_author_email
-  # * comment_author_url
-  # * comment_content
-  # * others representing HTTP headers and server environment vars
-  #
-  # See http://akismet.com/development/api/#comment-check for more info.
-  #
-  class Service
-
-    def verify_key( api_key, home_url )
-      response = invoke( 'verify-key', 'rest.akismet.com', :blog => home_url,
-        :key => api_key )
-
-      response.is_a?( Net::HTTPOK ) && response.body == 'valid'
-    end
-
-    def comment_check( api_key, home_url, user_ip, user_agent, params = {} )
-      response = invoke_comment_method 'comment-check', api_key, home_url,
-        user_ip, user_agent, params
-
-      response.is_a?( Net::HTTPOK ) && response.body == 'true'
-    end
-
-    def submit_ham( api_key, home_url, user_ip, user_agent, params = {} )
-      invoke_comment_method 'submit-ham', api_key, home_url, user_ip,
-        user_agent, params
-
-      nil
-    end
-
-    def submit_spam( api_key, home_url, user_ip, user_agent, params = {} )
-      invoke_comment_method 'submit-spam', api_key, home_url, user_ip,
-        user_agent, params
-
-      nil
-    end
-
-  private
-
-    def invoke_comment_method( method_name, api_key, home_url, user_ip, user_agent, params = {} )
-      host = "#{ api_key }.rest.akismet.com"
-
-      params = params.merge :blog => home_url,
-        :user_ip => user_ip,
-        :user_agent => user_agent
-
-      invoke method_name, host, params
-    end
-
-    # returns an HTTP response
-    def invoke( method_name, host, params )
-      path = "/#{ AKISMET_VERSION }/#{ method_name }"
-      data = url_encode( params )
-
-      Net::HTTP.start( host, PORT ) do |http|
-        http.post( path, data, HEADERS )
-      end
-    end
-
-    def url_encode( hash = {} )
-      hash.collect do |k, v|
-        "#{ CGI.escape( k.to_s ) }=#{ CGI.escape( v.to_s ) }"
-      end.join( "&" )
-    end
-
-  end
-end