Class: Viking::Defensio

Inherits:
Base show all
Defined in:
lib/viking/defensio.rb

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes inherited from Base

#options

Instance Method Summary collapse

Methods inherited from Base

#invalid_options?, #logger, logger, #mark_as_spam_or_ham

Constructor Details

#initialize(options) ⇒ Defensio

Create a new instance of the Akismet class

Arguments

Arguments are provided in the form of a Hash with the following keys (as Symbols) available:

api_key

your Defensio API key

blog

the blog associated with your api key

The following keys are available and are entirely optional. They are available incase communication with Akismet’s servers requires a proxy port and/or host:

  • proxy_port

  • proxy_host



59
60
61
62
 
# File 'lib/viking/defensio.rb', line 59

def initialize(options)
  super
  self.verify_options = false
end

Class Attribute Details

.api_version ⇒ Object

Returns the value of attribute api_version.



26
27
28
 
# File 'lib/viking/defensio.rb', line 26

def api_version
  @api_version
end

.host ⇒ Object

Returns the value of attribute host.



24
25
26
 
# File 'lib/viking/defensio.rb', line 24

def host
  @host
end

.port ⇒ Object

Returns the value of attribute port.



25
26
27
 
# File 'lib/viking/defensio.rb', line 25

def port
  @port
end

.service_type ⇒ Object

Returns the value of attribute service_type.



28
29
30
 
# File 'lib/viking/defensio.rb', line 28

def service_type
  @service_type
end

.standard_headers ⇒ Object

Returns the value of attribute standard_headers.



27
28
29
 
# File 'lib/viking/defensio.rb', line 27

def standard_headers
  @standard_headers
end

Instance Attribute Details

#last_response ⇒ Object (readonly)

Returns the value of attribute last_response.



34
35
36
 
# File 'lib/viking/defensio.rb', line 34

def last_response
  @last_response
end

#proxy_host ⇒ Object

Returns the value of attribute proxy_host.



33
34
35
 
# File 'lib/viking/defensio.rb', line 33

def proxy_host
  @proxy_host
end

#proxy_port ⇒ Object

Returns the value of attribute proxy_port.



32
33
34
 
# File 'lib/viking/defensio.rb', line 32

def proxy_port
  @proxy_port
end

Instance Method Details

#check_article(options = {}) ⇒ Object

This action should be invoked upon the publication of an article to announce its existence. The actual content of the article is sent to Defensio for analysis.

Arguments

Provided in a Hash with the following keys:

owner_url (required)

the URL of the owner using Defensio. Note that this value should be provided in your default options for Viking and will be automatically inserted into your call.

article_author (required)

the name of the author of the article

article_author_email (required)

the email address of the article’s author

article_title (required)

the title of the article

article_content (required)

the contents of the article

permalink (required)

the permalink of the article

Returns

Hash

contains server response. Should things go awry, the full response will be provided.

Response structure

The following are the fields returned from the server and their possible values:

status

indicates whether or not the key is valid for this blog. Either ‘success’ or ‘fail’.

message

the message provided by the action, if applicable

api_version

the API version used to process the request



112
113
114
115
 
# File 'lib/viking/defensio.rb', line 112

def check_article(options = {})
  return false if invalid_options?
  call_defensio 'announce-article', options
end

#check_comment(options = {}) ⇒ Object

This central action determines not only whether Defensio thinks a comment is spam or not, but also a measure of its “spaminess”, i.e. its relative likelihood of being spam.

It should be noted that one of Defensio’s key features is its ability to rank spam according to how “spammy” it appears to be. In order to make the most of the Defensio system in their applications, developers should take advantage of the spaminess value returned by this function, to build interfaces that make it easy for the user to quickly sort through and manage their spamboxes.

Arguments

Provide arguments in a Hash. The following keys are available:

owner_url (required)

the URL of the owner using Defensio. Note that this value should be provided in your default options for Viking and will be automatically inserted into your call.

user_ip (required)

the IP address of whomever is posting the comment

article_date <~strftime> (required)

the date the original blog article was posted

comment_author (required)

the name of the author of the comment

comment_type (required)

the type of comment being posted to the article. This is expected to be any of the following: ‘comment’, ‘trackback’, ‘pingback’, ‘other’

comment_content

the content of the comment in question

comment_author_email

the email address of the comment’s author

permalink

the permalink of the blog post to which the comment is being posted

referrer

the URL of the site that brought the commenter to this page

user_logged_in

whether or not the user leaving the comment is logged into the client platform. Expected to be either true or false.

trusted_user

whether or not the user is an administrator or modertor or editor of the blog. This should only ever be true if the blogging platform can guarentee that the user has been authenticated and authorized for this role. This is expected to be either true or false.

openid

the OpenID URL of the currently logged in user. Must be used in conjunction with user_logged_in as true. OpenID authentication must be taken care of by your application.

test_force

FOR TESTING PURPOSES ONLY: use this parameter to force the outcome of audit_comment. Optionally affix (with a comma) a desired spaminess return value (in the range 0 to 1) (e.g. “spam,x.xxxx” “ham,x.xxxx” )

Returns

Hash

contains server response. Should things go awry, the full response will be provided.

Response structure

The following are the fields returned from the server and their possible values:

status

indicates whether or not the key is valid for this blog. Either ‘success’ or ‘fail’.

message

the message provided by the action, if applicable

api_version

the API version used to process the request

signature

this uniquely identifies a message in the Defensio system. This should be retained by the client for retraining purposes.

spam

whether or not Defensio believes the comment to be spam. This will be either true or false

spaminess

a value indicating the relative likelihood that a comment is spam. This should be retained to aid in building spam sorting interfaces.



195
196
197
198
199
 
# File 'lib/viking/defensio.rb', line 195

def check_comment(options = {})
  return false if invalid_options?
  options[:article_date] = options[:article_date].strftime("%Y/%m/%d") # e.g. 2007/05/16
  call_defensio 'audit-comment', options
end

#mark_as_ham(options = {}) ⇒ Object

This action is used to retrain false positives. That is to say, to indicate to the filter that comments originally tagged as spam were in fact “ham” (i.e. legitimate comments).

Retraining the filter in this manner contributes to a personalized learning effect on the filtering algorithm that will improve accuracy for each user over time.

Arguments

Provide arguments in a Hash. The following keys are available:

owner_url (required)

the URL of the owner using Defensio. Note that this value should be provided in your default options for Viking and will be automatically inserted into your call.

signatures (comma separated Strings)(required)

a comma separated list of signatures (or single entry) to be submitted for retraining. The signatures were provided by Defensio when a comment was first audited.

Returns

Hash

contains server response. Should things go awry, the full response will be provided.

Response structure

The following are the fields returned from the server and their possible values:

status

indicates whether or not the key is valid for this blog. Either ‘success’ or ‘fail’.

message

the message provided by the action, if applicable

api_version

the API version used to process the request



278
279
280
281
 
# File 'lib/viking/defensio.rb', line 278

def mark_as_ham(options = {})
  return false if invalid_options?
  call_defensio 'report-false-positives', options
end

#mark_as_spam(options = {}) ⇒ Object

This action is used to retrain false negatives. That is to say, to indicate to the filter that comments originally tagged as “ham” (i.e. legitimate) were in fact spam.

Retraining the filter in this manner contributes to a personalized learning effect on the filtering algorithm that will improve accuracy for each user over time.

Arguments

Provide arguments in a Hash. The following keys are available:

owner_url (required)

the URL of the owner using Defensio. Note that this value should be provided in your default options for Viking and will be automatically inserted into your call.

signatures (comma separated Strings)(required)

a comma separated list of signatures (or single entry) to be submitted for retraining. The signatures were provided by Defensio when a comment was first audited.

Returns

Hash

contains server response. Should things go awry, the full response will be provided.

Response structure

The following are the fields returned from the server and their possible values:

status

indicates whether or not the key is valid for this blog. Either ‘success’ or ‘fail’.

message

the message provided by the action, if applicable

api_version

the API version used to process the request



237
238
239
240
 
# File 'lib/viking/defensio.rb', line 237

def mark_as_spam(options = {})
  return false if invalid_options?
  call_defensio 'report-false-negatives', options
end

#stats ⇒ Object

This action returns basic statistics regarding the performance of Defensio since activation

Returns

Hash

contains server response. Should things go awry, the full response will be provided.

Response structure

The following are the fields returned from the server and their possible values:

status

indicates whether or not the key is valid for this blog. Either ‘success’ or ‘fail’.

message

the message provided by the action, if applicable

api_version

the API version used to process the request

accuracy

a value between 0 and 1 representing the percentage of comments correctly identified as spam or ham by Defensio on this blog

spam

the number of spam comments caught by the filter

ham

the number of legitimate comments caught by the filter

false_positives

the number of times legitimate messages have been retrained (i.e. “de-spammed”) by the user

false_negatives

the number of times a comments had to be marked as spam by the user

learning

whether or not Defensio is still in its initial learning phase (either true or false)

learning_status

more reasons on why Defensio is still learning



319
320
321
322
 
# File 'lib/viking/defensio.rb', line 319

def stats
  return false if invalid_options?
  call_defensio 'get-stats'
end

#url(action) ⇒ Object

Formats a URL for use with the Defensio service.

Arguments

action <String>

the action you wish to call

Returns

String

Example

> defensio.url('get-stats')
=> '/blog/1.2/get-stats/1234abc.yaml'



335
336
337
338
339
340
341
342
343
344
345
 
# File 'lib/viking/defensio.rb', line 335

def url(action)
  URI.escape(
    [
      '', # ensures opening /
      self.class.service_type,
      self.class.api_version,
      action,
      self.options[:api_key]
    ].join('/')
  ) << '.yaml'
end

#verified? ⇒ Boolean

This action verifies that the key is valid for the owner calling the service. A user must have a valid API key in order to use Defensio.

Returns

true, false

Returns:

  • (Boolean) 


69
70
71
72
 
# File 'lib/viking/defensio.rb', line 69

def verified?
  return false if invalid_options?
  (@verify_options ||= call_defensio('validate-key'))[:status] == 'success'
end