class Akismet::Client
Constants
- PARAM_TO_API_PARAM
Attributes
The API key obtained at akismet.com @return [String]
The name of the application making the request @return [String]
A URL that identifies the application making the request @return [String]
The version of the application making the request @return [String]
Public Class Methods
@param [String] #api_key
The API key obtained at akismet.com
@param [String] #app_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 provided.
# File lib/akismet/client.rb, line 39 def initialize(api_key, app_url, options = {}) @api_key = api_key @app_url = app_url @app_name = options[ :app_name ] @app_version = options[ :app_version ] @http_session = nil end
Initializes a client, opens it, yields it to the given block, and closes it when the block returns. Allows you to perform several operations over a single TCP connection. @param (see initialize) @option (see initialize) @yieldparam [Client] client @return [Object]
The return value of the block
@see open
# File lib/akismet/client.rb, line 59 def self.open(api_key, app_url, options = {}) raise "Block required" unless block_given? client = new(api_key, app_url) client.open { yield client } end
Public Instance Methods
Checks whether a comment is spam and whether it is “blatant.” @!macro akismet_method @return [(Boolean, Boolean)]
An array containing two booleans. The first indicates whether the comment is spam. The second indicates whether it is "blatant," i.e. whether it can be deleted without review.
# File lib/akismet/client.rb, line 191 def check(user_ip, user_agent, params = {}) response = invoke_comment_method('comment-check', user_ip, user_agent, params) unless %w{ true false }.include?(response.body) raise_with_response response end [ response.body == 'true', response['X-akismet-pro-tip'] == 'discard' ] end
Submits a comment that has been identified as not-spam (ham). @!macro akismet_method @return [void]
# File lib/akismet/client.rb, line 222 def ham(user_ip, user_agent, params = {}) response = invoke_comment_method('submit-ham', user_ip, user_agent, params) unless response.body == 'Thanks for making the web a better place.' raise_with_response response end end
Opens the client, creating a new TCP connection.
If a block is given, yields to the block, closes the client when the block returns, and returns the return value of the block. If a block is not given, returns self and leaves the client open, relying on the caller to close the client with {#close}.
Note that opening and closing the client is only required if you want to make several calls over one TCP connection. Otherwise, you can simply call {#spam?}, {#check}, {#ham}, or {#spam}, which call {#open} for you if necessary.
Due to a peculiarity of the Akismet API, {#verify_key} always creates its own connection.
@overload open
Opens the client, yields to the block, and closes the client when the block returns. @yield A block to be called when the client is open @return [Object] The return value of the block @raise [StandardError] The client is already open
@overload open
@return [self] @raise [StandardError] The client is already open
# File lib/akismet/client.rb, line 94 def open raise "Already open" if open? @http_session = Net::HTTP.new( "#{ api_key }.rest.akismet.com", 80 ) begin @http_session.start block_given? ? yield : self ensure close if block_given? end end
Whether the Client is open. @return [Boolean]
# File lib/akismet/client.rb, line 120 def open? @http_session && @http_session.started? end
Submits a comment that has been identified as spam. @!macro akismet_method @return [void]
# File lib/akismet/client.rb, line 238 def spam(user_ip, user_agent, params = {}) response = invoke_comment_method('submit-spam', user_ip, user_agent, params) unless response.body == 'Thanks for making the web a better place.' raise_with_response response end end
Checks whether a comment is spam. @!macro akismet_method @return [Boolean]
# File lib/akismet/client.rb, line 212 def spam?(user_ip, user_agent, params = {}) check(user_ip, user_agent, params)[0] end
Checks the validity of the API key. @return [Boolean]
# File lib/akismet/client.rb, line 129 def verify_key response = Net::HTTP.start('rest.akismet.com', 80) do |session| invoke session, 'verify-key', blog: app_url, key: api_key end unless %w{ valid invalid }.include?(response.body) raise_with_response response end response.body == 'valid' end
Private Instance Methods
@param [Object] object @return [String]
# File lib/akismet/client.rb, line 331 def format(object) case object when DateTime object.iso8601 when TrueClass '1' when FalseClass '0' when Array object.collect { |element| format(element) }.join(', ') else object.to_s end end
@return [Hash]
# File lib/akismet/client.rb, line 347 def http_headers { 'User-Agent' => user_agent, 'Content-Type' => 'application/x-www-form-urlencoded' } end
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]
# File lib/akismet/client.rb, line 259 def in_http_session if open? yield @http_session else open { yield @http_session } end 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.
# File lib/akismet/client.rb, line 311 def invoke(http_session, method_name, params = {}) params[:blog_charset] = 'UTF-8' params = params.collect do |name, value| [name.to_s.encode('UTF-8'), format(value).encode('UTF-8')] end response = http_session.post("/1.1/#{ method_name }", URI.encode_www_form(params), http_headers) unless response.is_a?( Net::HTTPOK ) raise Error, "HTTP #{ response.code } received (expected 200)" end response end
@param [String] method_name @param [String] user_ip @param [String] #user_agent @param [Hash] params @return [Net::HTTPResponse] @raise [ArgumentError]
An environment variable conflicts with a built-in parameter
@raise [ArgumentError]
Invalid parameter
# File lib/akismet/client.rb, line 282 def invoke_comment_method(method_name, user_ip, user_agent, params = {}) env = params[:env] || {} for key in env.keys if PARAM_TO_API_PARAM.has_value?(key.to_sym) raise ArgumentError, "Environment variable '#{key}' conflicts with built-in API parameter" end end params = params.each_with_object(Hash.new) do |(name, value), api_params| next if name == :env api_name = PARAM_TO_API_PARAM[name] || raise(ArgumentError, "Invalid param: #{name}") api_params[api_name] = value end params = env.merge(params).merge(blog: app_url, user_ip: user_ip, user_agent: user_agent) in_http_session do |session| invoke session, method_name, params end end
@param [Net::HTTPResponse] response
# File lib/akismet/client.rb, line 268 def raise_with_response( response ) raise Error, response['X-akismet-debug-help'] || 'Unknown error' 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]
# File lib/akismet/client.rb, line 359 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]
# File lib/akismet/client.rb, line 366 def user_agent_app app_name && [app_name, app_version].compact.join("/") end
@return [String]
# File lib/akismet/client.rb, line 371 def user_agent_plugin "Ruby Akismet/#{ Akismet::VERSION }" end