visual_captcha 0.0.1 → 0.0.2

data/README.md

@@ -1,4 +1,146 @@
-visualCaptcha-rubyGem
-=====================
+[![Build Status](https://travis-ci.org/emotionLoop/visualCaptcha-rubyGem.svg?flat=true&branch=master)](https://travis-ci.org/emotionLoop/visualCaptcha-rubyGem)
+[![Codacy](https://www.codacy.com/project/badge/4d1f731df8ea4dfe99b51032f92fc371)](https://www.codacy.com/app/bruno-bernardino/visualCaptcha-rubyGem)
+[![Code Climate](https://codeclimate.com/github/emotionLoop/visualCaptcha-rubyGem/badges/gpa.svg)](https://codeclimate.com/github/emotionLoop/visualCaptcha-rubyGem)
+
+# visualCaptcha-rubyGem
 
 RubyGem package for visualCaptcha's backend service
+
+
+## Installation with Gem
+
+You need Ruby 1.9.3+ installed.
+```
+gem install visual_captcha
+```
+
+## Run tests
+
+You need Bundler and Rake installed and then you can run
+```
+bundle install && rake
+```
+
+
+## Usage
+
+### Initialization
+
+You have to initialize a session for visualCaptcha to inject the data it needs. You'll need this variable to start and verify visualCaptcha as well.
+
+```
+@session = VisualCaptcha::Session.new session, @namespace
+```
+Where:
+
+- `@namespace` is optional. It's a string and defaults to 'visualcaptcha'. You'll need to specifically set this if you're using more than one visualCaptcha instance in the same page, so the code can identify from which one is the validation coming from.
+
+
+### Setting Routes for the front-end
+
+You also need to set routes for `/start/:howmany`, `/image/:index`, and `/audio/:type`. These will usually look like:
+
+```ruby
+get '/start/:how_many' do
+    captcha = VisualCaptcha::Captcha.new @session
+    captcha.generate params[:how_many]
+
+    json captcha.frontend_data
+  end
+
+  get '/audio/?:type?' do
+    type = params[:type]
+    type = 'mp3' if type != 'ogg'
+
+    captcha = VisualCaptcha::Captcha.new @session
+
+    if (@body = captcha.stream_audio @headers, type)
+      body @body
+    else
+      not_found
+    end
+  end
+
+  get '/image/:index' do
+    captcha = VisualCaptcha::Captcha.new @session
+
+    if (@body = captcha.stream_image @headers, params[:index], params[:retina])
+      body @body
+    else
+      not_found
+    end
+  end
+```
+
+### Validating the image/audio
+
+Here's how it'll usually look:
+
+```ruby
+@session = VisualCaptcha::Session.new session
+captcha = VisualCaptcha::Captcha.new @session
+frontend_data = captcha.frontend_data()
+
+# If an image field name was submitted, try to validate it
+if ( image_answer = params[ frontend_data[ 'imageFieldName' ] ] )
+  if captcha.validate_image image_answer
+    # Image was valid.
+  else
+    # Image was submitted, but wrong.
+  end
+elsif ( audio_answer = params[ frontend_data[ 'audioFieldName' ] ] )
+  if captcha.validate_audio audio_answer.downcase
+    # Audio answer was valid.
+  else
+    # Audio was submitted, but wrong.
+  end
+else
+  # Apparently no fields were submitted, so the captcha wasn't filled.
+end
+```
+
+### VisualCaptcha::Session properties
+
+- `:session`, Object — The object that will hold the session data for visualCaptcha.
+- `:namespace`, String — This is private and will hold the namespace for each visualCaptcha instance. Defaults to 'visualcaptcha'.
+
+### VisualCaptcha::Session methods
+
+- `initialize( :session, :namespace )` — Initialize the visualCaptcha session.
+- `clear()` — Will clear the session for the current namespace.
+- `get( :key )` — Will return a value for the session's `:key`.
+- `set( :key, :value )` — Set the `:value` for the session's `:key`.
+
+
+### VisualCaptcha::Captcha properties
+
+- `@session`, Object that will have a reference for the session object.
+  It will have .visualCaptcha.images, .visualCaptcha.audios, .visualCaptcha.validImageOption, and .visualCaptcha.validAudioOption.
+- `@assets_path`, Assets path. By default, it will be './assets'
+- `@image_options`, All the image options.
+  These can be easily overwritten or extended using addImageOptions( <Array> ), or replaceImageOptions( <Array> ). By default, they're populated using the ./images.json file
+- `@audio_options`, All the audio options.
+  These can be easily overwritten or extended using addAudioOptions( <Array> ), or replaceAudioOptions( <Array> ). By default, they're populated using the ./audios.json file
+
+### VisualCaptcha::Captcha methods
+
+You'll find more documentation on the code itself, but here's the simple list for reference.
+
+- `initialize(session, assets_path = nil, default_images = nil, default_audios = nil)` — Initialize the visualCaptcha object.
+- `generate(number_of_options = 5)` — Will generate a new valid option, within a `:numberOfOptions`.
+- `stream_audio(headers, file_type = 'mp3')` — Stream audio file.
+- `stream_image(headers, index, is_retina)` — Stream image file given an index in the session visualCaptcha images array.
+- `frontend_data()` — Get data to be used by the frontend.
+- `valid_image_option()` — Get the current validImageOption.
+- `valid_audio_option()` — Get the current validAudioOption.
+- `validate_image( sent_option )` — Validate the sent image value with the validImageOption.
+- `validate_audio( sent_option )` — Validate the sent audio value with the validAudioOption.
+- `selected_images()` — Return generated image options.
+- `getAudioOption()` — Alias for getValidAudioOption.
+- `all_image_options()` — Return all the image options.
+- `all_audio_options()` — Return all the audio options.
+
+
+## License
+
+MIT. Check the [LICENSE](LICENSE) file.

data/lib/visual_captcha/captcha.rb

@@ -2,6 +2,10 @@ require 'json'
 require 'securerandom'
 
 class VisualCaptcha::Captcha
+  # @param session is the default session object
+  # @param assets_path is optional. Defaults to 'assets'. The path is relative to /
+  # @param default_images is optional. Defaults to the array inside ./images.json. The path is relative to ./images/
+  # @param default_audios is optional. Defaults to the array inside ./audios.json. The path is relative to ./audios/
   def initialize(session, assets_path = nil, default_images = nil, default_audios = nil)
     @session = session
 
@@ -15,11 +19,13 @@ class VisualCaptcha::Captcha
     @audio_options ||= JSON.load File.read("#{@assets_path}/audios.json")
   end
 
+  # Generate a new valid option
+  # @param numberOfOptions is optional. Defaults to 5
   def generate(number_of_options = 5)
     @session.clear
 
     number_of_options = number_of_options.to_i
-    number_of_options = 2 if number_of_options < 2
+    number_of_options = 4 if number_of_options < 4
 
     images = all_image_options.sample number_of_options
     images.each do |image|
@@ -40,6 +46,9 @@ class VisualCaptcha::Captcha
     }
   end
 
+  # Stream audio file
+  # @param headers object. used to store http headers for streaming
+  # @param fileType defaults to 'mp3', can also be 'ogg'
   def stream_audio(headers, file_type = 'mp3')
     audio_option = valid_audio_option
     return nil if audio_option.nil?
@@ -58,6 +67,10 @@ class VisualCaptcha::Captcha
     read_file headers, audio_file_path, content_type
   end
 
+  # Stream image file given an index in the session visualCaptcha images array
+  # @param headers object. used to store http headers for streaming
+  # @param index of the image in the session images array to send
+  # @paran isRetina boolean. Defaults to false
   def stream_image(headers, index, is_retina)
     image_option = selected_image_at_index index.to_i
     return nil if image_option.nil?
@@ -116,6 +129,11 @@ class VisualCaptcha::Captcha
     headers['Pragma'] = 'no-cache'
     headers['Expires'] = '0'
 
-    File.read file_path
+    file_contents = File.read file_path
+
+    # Add some noise randomly, so images can't be saved and matched easily by filesize or checksum
+    file_contents += SecureRandom.hex(SecureRandom.random_number(1500))
+
+    return file_contents
   end
 end

data/lib/visual_captcha/version.rb

@@ -1,3 +1,3 @@
 module VisualCaptcha
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,69 +1,78 @@
 --- !ruby/object:Gem::Specification
 name: visual_captcha
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
+  prerelease: 
 platform: ruby
 authors:
 - emotionLoop
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-30 00:00:00.000000000 Z
+date: 2015-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: RubyGem package for visualCaptcha's backend service
@@ -72,7 +81,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
+- .gitignore
 - Gemfile
 - LICENSE
 - README.md
@@ -204,26 +213,27 @@ files:
 homepage: http://emotionloop.com
 licenses:
 - MIT
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 1.8.23
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: visualCaptcha RubyGem Package
 test_files:
 - spec/lib/visual_captcha/captcha_spec.rb

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: b8982b9d2f00d6f0b0ba6365d1ec6113b8aa5416
-  data.tar.gz: 1cc363dd419a646bb07f998cb3bd61de35a82ea7
-SHA512:
-  metadata.gz: a8df46eb4212c3ac44e56cc15a3c72bc4d53fcc37a98e1fb42859672eca3c76f90e2671b7858a310643cff8d1abc6c73a3c2a9bb81be491fec886a2551f7d50b
-  data.tar.gz: 238135b202959da80c35f2d7d5270fc76b647dad5e0a32af07b4a6718f71091a572d2ce8f9d569621cba7593197dfb60f49fe83b389d892abbd7e6fd60889975