acts_as_textcaptcha 4.3.0 → 4.4.1

data/README.md

@@ -1,287 +1,258 @@
 ## ActAsTextcaptcha
 
-[![Gem Version](https://img.shields.io/gem/v/acts_as_textcaptcha.svg?style=flat)](http://rubygems.org/gems/acts_as_textcaptcha)
-[![Travis Build Status](https://travis-ci.org/matthutchinson/acts_as_textcaptcha.svg?branch=master)](https://travis-ci.org/matthutchinson/acts_as_textcaptcha)
-[![Maintainability](https://img.shields.io/codeclimate/maintainability/matthutchinson/acts_as_textcaptcha.svg)](https://codeclimate.com/github/matthutchinson/acts_as_textcaptcha/maintainability)
-[![Gem Dependency Status](https://gemnasium.com/badges/github.com/matthutchinson/acts_as_textcaptcha.svg)](https://gemnasium.com/github.com/matthutchinson/acts_as_textcaptcha)
-
-ActsAsTextcaptcha provides spam protection for your Rails models using logic
-questions from the excellent [TextCaptcha](http://textcaptcha.com/) web service
-(by [Rob Tuley](https://twitter.com/robtuley). It is also possible to configure your
-own captcha questions (instead, or as a fallback in the event of any API
-issues).
-
-This gem is actively maintained, has good test coverage and is compatible with
-Rails >= 3 (including Rails 4 & 5) and Ruby >= 2.1. If you have issues
-please report them
-[here](https://github.com/matthutchinson/acts_as_textcaptcha/issues/new).
-
-Logic questions from the web service are aimed at a child's age of 7, so they
-can be solved easily by even the most cognitively impaired users. As they
-involve human logic, questions cannot be solved by a robot. There are both
-advantages and disadvantages in using logic questions over image based
-captchas, find out more at [TextCaptcha](http://textcaptcha.com/).
+[![Gem](https://img.shields.io/gem/v/acts_as_textcaptcha.svg?style=flat)](http://rubygems.org/gems/acts_as_textcaptcha)
+[![Travis](https://img.shields.io/travis/matthutchinson/acts_as_textcaptcha/master.svg?style=flat)](https://travis-ci.org/matthutchinson/acts_as_textcaptcha)
+[![Depfu](https://img.shields.io/depfu/matthutchinson/acts_as_textcaptcha.svg?style=flat)](https://depfu.com/github/matthutchinson/acts_as_textcaptcha)
+[![Maintainability](https://api.codeclimate.com/v1/badges/c67969dd7b921477bdcc/maintainability)](https://codeclimate.com/github/matthutchinson/acts_as_textcaptcha/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/c67969dd7b921477bdcc/test_coverage)](https://codeclimate.com/github/matthutchinson/acts_as_textcaptcha/test_coverage)
+
+ActsAsTextcaptcha provides spam protection for Rails models with a text-based
+logic question captcha. Questions are fetched from [Rob
+Tuley's](https://twitter.com/robtuley)
+[textcaptcha.com](http://textcaptcha.com/). They can be solved easily by humans
+but are tough for robots to crack.
+
+The gem can also be configured with your own questions; as an alternative, or as
+a fallback to handle any API issues. For reasons on why logic based captchas
+are a good idea visit [textcaptcha.com](http://textcaptcha.com).
+
+## Requirements
+
+* [Ruby](http://ruby-lang.org/) >= 2.1.0
+* [Rails](http://github.com/rails/rails) >= 3
+* [Rails.cache](http://guides.rubyonrails.org/caching_with_rails.html#cache-stores)
 
 ## Demo
 
 Try a [working demo here](https://acts-as-textcaptcha-demo.herokuapp.com)!
-
-**Or** click below to deploy your own example Rails app to Heroku (already
-configured with acts_as_textcaptcha). See
-[here](https://github.com/matthutchinson/acts_as_textcaptcha_demo) for more
-details.
+**Or** one-click deploy your own demo app at Heroku. See
+[here](https://github.com/matthutchinson/acts_as_textcaptcha_demo) for details.
 
 [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://www.heroku.com/deploy?template=https://github.com/matthutchinson/acts_as_textcaptcha_demo/tree/master)
 
-## Installing
+## Installation
 
-First add the following to your Gemfile, then `bundle install`;
+Add this line to your Gemfile and run `bundle install`:
 
-    gem 'acts_as_textcaptcha'
+```ruby
+gem 'acts_as_textcaptcha'
+```
 
-Add the following code to models you would like to protect;
+Add this to models you'd like to protect:
 
-    class Comment < ApplicationRecord
-      # (this is the simplest way to configure the gem)
-      acts_as_textcaptcha :api_key => 'TEXTCAPTCHA_API_IDENTITY'
-    end
+```ruby
+class Comment < ApplicationRecord
+  acts_as_textcaptcha api_key: 'TEXTCAPTCHA_API_IDENTITY'
+  # see below for more config options
+end
+```
 
-Your `TEXTCAPTCHA_API_IDENTITY` should be some reference to yourself (e.g. an
-email address, domain or similar where if there are problems with your usage you
-can be contacted).
+[Rob](https://twitter.com/robtuley) requests that your
+`TEXTCAPTCHA_API_IDENTITY` be some reference to yourself (e.g. an email address,
+domain or similar) so you can be contacted should any usage problem occur.
 
-Next, in your controller's *new* action generate and assign the logic question
-for the record, like so;
+In your controller's `new` action call the `textcaptcha` method:
 
-    def new
-      @comment = Comment.new
-      @comment.textcaptcha
-    end
+```ruby
+def new
+  @comment = Comment.new
+  @comment.textcaptcha   
+end
+```
 
-Finally, in the view add the textcaptcha question and answer fields to your form
-using the `textcaptcha_fields` helper. Feel free to arrange the HTML within this
-block as you like;
+Finally add the question and answer fields to your form using the
+`textcaptcha_fields` helper. Arrange the HTML within this block as you like.
 
-    <%= textcaptcha_fields(f) do %>
-      <div class="field">
-        <%= f.label :textcaptcha_answer, @comment.textcaptcha_question %><br/>
-        <%= f.text_field :textcaptcha_answer, :value => '' %>
-      </div>
-    <% end %>
+```ruby
+<%= textcaptcha_fields(f) do %>
+  <div class="field">
+    <%= f.label :textcaptcha_answer, @comment.textcaptcha_question %><br/>
+    <%= f.text_field :textcaptcha_answer, :value => '' %>
+  </div>
+<% end %>
+```
 
-*NOTE:* If you'd rather NOT use this helper and prefer to write your own form
-elements, take a look at the HTML produced from this helper method
+If you'd prefer to construct your own form elements, take a look at the HTML
+produced
 [here](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/lib/acts_as_textcaptcha/textcaptcha_helper.rb).
 
-*NOTE:* The defaults for [cache
-configuration](http://guides.rubyonrails.org/caching_with_rails.html#cache-stores)
-changed with Rails 5 and this gem **requires** a working Rails.cache store to
-exist.
+## Configuration
 
-*NOTE:* These installation steps changed with v4.0.0 of this gem. If you are
-having problems please refer to the 3.0 [upgrade
-guide](https://github.com/matthutchinson/acts_as_textcaptcha/wiki/Upgrading-from-3.0.10).
+The following options are available (only `api_key` is required):
 
-### Toggling TextCaptcha
+* **api_key** (_required_) - a reference to yourself (e.g. your email or domain).
+* **questions** (_optional_) - array of your own questions and answers (see below).
+* **cache_expiry_minutes** (_optional_) - how long valid answers are cached for (default 10 minutes).
+* **raise_errors** (_optional_) - if true, API or network errors are raised (default false, errors logged).
+* **api_endpoint** (_optional_) - set your own JSON API endpoint to fetch from (see below).
 
-You can toggle textcaptcha on/off for your models by overriding the
-`perform_textcaptcha?` method. If it returns false, no questions will be fetched
-from the web service and captcha validation is disabled.
+For example:
 
-This is useful for writing your own custom logic for toggling spam protection
-on/off e.g. for logged in users. By default the `perform_textcaptcha?` method
-[checks if the object is a new (unsaved)
-record](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/lib/acts_as_textcaptcha/textcaptcha.rb#L54).
+```ruby
+class Comment < ApplicationRecord
+  acts_as_textcaptcha api_key: 'TEXTCAPTCHA_API_IDENTITY_KEY',
+                      raise_errors: false,
+                      cache_expiry_minutes: 10,
+                      questions: [
+                        { 'question' => '1+1', 'answers' => '2,two' },
+                        { 'question' => 'The green hat is what color?', 'answers' => 'green' }
+                      ]
+end
+```
 
-So out of the box, spam protection is only enabled for creating new records (not
-updating). Here is a typical example showing how to overwrite the
-`perform_textcaptcha?` method, while maintaining the new record check.
+### YAML config
 
-    class Comment < ApplicationRecord
-      acts_as_textcaptcha :api_key => 'TEXTCAPTCHA_API_IDENTITY'
+You can apply an app wide config with a `config/textcaptcha.yml` file. Use this
+rake task to add one from a
+[template](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/lib/acts_as_textcaptcha/textcaptcha_config.rb):
 
-      def perform_textcaptcha?
-        super && user.admin?
-      end
-    end
+    $ bundle exec rake textcaptcha:config
 
-### Configuration options
+**NOTE**: Any options set in models take preference over this config.
 
-You can configure captchas with the following options;
+### Config without the TextCaptcha service
 
-* *api_key* (_required_) - reference to yourself (e.g. your email - to identify calls to the textcaptcha.com API)
-* *questions* (_optional_) - array of question and answer hashes (see below) A random question from this array will be asked if the web service fails OR if no `api_key` has been set. Multiple answers to the same question are comma separated (e.g. 2,two). Don't use commas in your answers!
-* *cache_expiry_minutes* (_optional_) - minutes for answers to persist in the cache (default 10 minutes), see [below for details](https://github.com/matthutchinson/acts_as_textcaptcha#what-does-the-code-do)
-* *http_read_timeout* (_optional_) - Net::HTTP option, seconds to wait for one block to be read from the remote API
-* *http_open_timeout* (_optional_) - Net::HTTP option, seconds to wait for the connection to open to the remote API
+To use __only__ your own logic questions, omit the `api_key` and set them in the
+config (see above). Multiple answers to the same question must be comma
+separated e.g. `2,two` (so do not include commas in answers).
 
-For example;
+You can optionally set your own `api_endpoint` to fetch questions and answers
+from. The URL must respond with a JSON object like this:
 
-    class Comment < ApplicationRecord
-      acts_as_textcaptcha :api_key              => 'TEXTCAPTCHA_API_IDENTITY',
-                          :http_read_timeout    => 60,
-                          :http_read_timeout    => 10,
-                          :cache_expiry_minutes => 10,
-                          :questions            => [{ 'question' => '1+1', 'answers' => '2,two' },
-                                                    { 'question' => 'The green hat is what color?', 'answers' => 'green' }]
-    end
+```ruby
+{
+  "q": "What number is 4th in the series 39, 11, 31 and nineteen?",
+  "a": ["1f0e3dad99908345f7439f8ffabdffc4","1d56cec552bf111de57687e4b5f8c795"]
+}
+```
 
-#### YAML config
+With `"a"` being an array of answer strings, MD5'd, and lower-cased. The
+`api_key` option is ignored if an `api_endpoint` is set.
 
-The gem can be configured for models individually (as shown above) or with a
-config/textcaptcha.yml file. The config file must have an `api_key` defined
-and/or an array of questions and answers. Any options defined inline in model
-classes take preference over the global configuration in textcaptcha.yml.
+### Toggling TextCaptcha
 
-The gem comes with a handy rake task to copy over a
-[textcaptcha.yml](http://github.com/matthutchinson/acts_as_textcaptcha/raw/master/config/textcaptcha.yml)
-template to your config directory;
+Enable or disable captchas by overriding the `perform_textcaptcha?` method (in
+models). By default the method checks if the object is a new (unsaved) record.
+So spam protection is __only__ enabled for creating new records (not updating).
 
-    rake textcaptcha:config
+Here's an example overriding the default behaviour but maintaining the new
+record check.
 
-#### Configuring _without_ the TextCaptcha web service
+```ruby
+class Comment < ApplicationRecord
+  acts_as_textcaptcha :api_key => 'TEXTCAPTCHA_API_IDENTITY'
 
-To use only your own logic questions, simply omit the `api_key` from the
-configuration and define at least one logic question and answer (see above).
+  def perform_textcaptcha?
+    super && user.admin?
+  end
+end
+```
 
 ## Translations
 
-The gem uses the standard Rails I18n translation approach (with a fall-back to
-English). Unfortunately at present, the TextCaptcha web service only provides
-logic questions in English.
-
-    en:
-      activerecord:
-        errors:
-          models:
-            comment:
-              attributes:
-                textcaptcha_answer:
-                  incorrect: "is incorrect, try another question instead"
-                  expired: "was not submitted quickly enough, try another question instead"
-      activemodel:
-        attributes:
-          comment:
-            textcaptcha_answer: "TextCaptcha answer"
-
-## Without ActiveRecord
-
-It is possible to use this gem without ActiveRecord. As an example, take a look at the
-[Contact](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/test/test_models.rb#L44)
-model used in the test suite
-[here](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/test/test_models.rb#L44).
-
-## Testing and docs
-
-In development you can run the tests and rdoc tasks like so;
-
-* `rake test` (all tests)
-* `appraisal rake test` (all tests with all gemfile variations)
-* `appraisal rails-3 rake test` (all tests using a specific gemfile)
-* `rake rdoc` (generate docs)
-
-This gem uses [appraisal](https://github.com/thoughtbot/appraisal) to run the
-test suite with multiple versions of Rails.
-
-## What does the code do?
-
-The gem contains two parts, a module for your ActiveRecord models, and a single
-view helper method. The ActiveRecord module makes use of two futher classes,
-[TextcaptchaApi](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/lib/acts_as_textcaptcha/textcaptcha_api.rb)
-and
-[TextcaptchaCache](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/lib/acts_as_textcaptcha/textcaptcha_cache.rb).
-
-A call to `@model.textcaptcha` in your controller will query the TextCaptcha web
-service. A GET request is made with Net::HTTP and parsed using the default Rails
-`ActiveSupport::XMLMini` backend. A textcaptcha_question and a random cache key
-are assigned to the record. An array of possible answers is also stored in the
-TextcaptchaCache with this random key. The cached answers have (by default) a 10
-minute TTL in your cache. If your forms take more than 10 minutes to be
-completed you can adjust this value setting the `cache_expiry_minutes` option.
-Internally TextcaptchaCache wraps
-[Rails.cache](http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html)
-and all cache keys are name spaced.
-
-On saving, `validate_textcaptcha` is called on @model.validate checking that the
-`@model.textcaptcha_answer` matches one of the possible answers (retrieved from
-the cache). By default, this validation is _only_ carried out on new records,
-i.e. never on update, only on create. All attempted answers are case-insensitive
-and have trailing/leading white-space removed.
-
-Regardless of a correct, or incorrect answer the possible answers are cleared
-from the cache and a new random key is generated and assigned. An incorrect
-answer will cause a new question to be prompted. After one correct answer, the
-answer and a mutating key are sent on further form requests, and no question is
-presented in the form.
-
-If an error or timeout occurs during API fetching, ActsAsTextcaptcha will fall
-back to choose a random logic question defined in your options (see above). If
-the web service fails or no API key is specified AND no alternate questions are
-configured, the @model will not require textcaptcha checking and will pass as
-valid.
-
-For more details on the code please check the
-[documentation](http://rdoc.info/projects/matthutchinson/acts_as_textcaptcha).
-Tests are written with [MiniTest](https://rubygems.org/gems/minitest). Pull
-requests and bug reports are welcome.
+The following strings are translatable (with Rails I18n translations):
 
-## Requirements
+```yaml
+en:
+  activerecord:
+    errors:
+      models:
+        comment:
+          attributes:
+            textcaptcha_answer:
+              incorrect: "is incorrect, try another question instead"
+              expired: "was not submitted quickly enough, try another question instead"
+  activemodel:
+    attributes:
+      comment:
+        textcaptcha_answer: "TextCaptcha answer"
+```
+
+**NOTE**: The textcaptcha.com API only provides logic questions in English.
+
+## Handling Errors
+
+The API may be unresponsive or return an unexpected response. If you've set
+`raise_errors: true`, consider handling these errors:
+
+* `ActsAsTextcaptcha::ResponseError`
+* `ActsAsTextcaptcha::ParseError`
+* `ActsAsTextcaptcha::ApiKeyError`
+
+## Development
+
+Check out this repo and run `bin/setup`, this will install gem dependencies and
+generate docs. Use `bundle exec rake` to run tests and generate a coverage
+report.
+
+You can also run `bin/console` for an interactive prompt to experiment with the
+code.
+
+## Tests
+
+MiniTest is used for testing. Run the test suite with:
+
+    $ rake test
+
+This gem uses [appraisal](https://github.com/thoughtbot/appraisal) to test
+against multiple versions of Rails.
 
-What do you need?
+* `appraisal rake test` (run tests against all Gemfile variations)
+* `appraisal rails-3 rake test` (run tests against a specific Gemfile)
 
-* [Rails](http://github.com/rails/rails) >= 3  (including Rails 4 & 5)
-* [Rails.cache](http://guides.rubyonrails.org/caching_with_rails.html#cache-stores) - a basic cache configuration is necessary
-* [Ruby](http://ruby-lang.org/) >= 2.1
+## Docs
 
-*NOTE:* The built-in
-[TextcaptchaCache](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/lib/acts_as_textcaptcha/textcaptcha_cache.rb)
-class directly wraps the
-[Rails.cache](http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html).
-An alternative TextcaptchaCache implementation will be necessary if
-`Rails.cache` is not available.
+Generate docs for this gem with:
 
+    $ rake rdoc
 
-## Rails 2 Support
+## Troubles?
 
-Support for Rails 2 was dropped with the release of `v4.1.0`. If you would like
-to continue to use this gem with an older version of Rails (>= 2.3.8), please
-lock your Gemfile with version `4.0.0`. Like so;
+If you think something is broken or missing, please raise a new
+[issue](https://github.com/matthutchinson/acts_as_textcaptcha/issues). Please
+remember to check it hasn't already been raised.
 
-    # in your Gemfile
-    gem 'acts_as_textcaptcha', '=4.0.0'
+## Contributing
 
-    # or in config/environment.rb
-    config.gem 'acts_as_textcaptcha', :version => '=4.0.0'
+Bug [reports](https://github.com/matthutchinson/acts_as_textcaptcha/issues) and
+[pull requests](https://github.com/matthutchinson/acts_as_textcaptcha/pulls) are
+welcome on GitHub. When submitting pull requests, remember to add tests covering
+any new behaviour, and ensure all tests are passing on
+[Travis](https://travis-ci.org/matthutchinson/acts_as_textcaptcha). Read the
+[contributing
+guidelines](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/CONTRIBUTING.md)
+for more details.
 
-Check out the
-[README](https://github.com/matthutchinson/acts_as_textcaptcha/tree/v4.0.0) for
-this release for further instructions.
+This project is intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the [Contributor
+Covenant](http://contributor-covenant.org) code of conduct. See
+[here](https://github.com/matthutchinson/acts_as_textcaptcha/blob/master/CODE_OF_CONDUCT.md)
+for more details.
+
+## Todo
+
+* Allow translatable user supplied questions and answers in config
+* Allow `Net::HTTP` to be swapped out for any another HTTP client.
+
+## License
+
+The code is available as open source under the terms of
+[LGPL-3](https://opensource.org/licenses/LGPL-3.0).
+
+## Who's who?
+
+* [ActsAsTextcaptcha](http://github.com/matthutchinson/acts_as_textcaptcha) and [little robot drawing](http://www.flickr.com/photos/hiddenloop/4541195635/) by [Matthew Hutchinson](http://matthewhutchinson.net)
+* [TextCaptcha](http://textcaptcha.com) API and service by [Rob Tuley](https://twitter.com/robtuley)
 
 ## Links
 
 * [Demo](https://acts-as-textcaptcha-demo.herokuapp.com)
 * [Travis CI](http://travis-ci.org/#!/matthutchinson/acts_as_textcaptcha)
 * [Maintainability](https://codeclimate.com/github/matthutchinson/acts_as_textcaptcha/maintainability)
+* [Test Coverage](https://codeclimate.com/github/matthutchinson/acts_as_textcaptcha/test_coverage)
 * [RDoc](http://rdoc.info/projects/matthutchinson/acts_as_textcaptcha)
 * [Wiki](http://wiki.github.com/matthutchinson/acts_as_textcaptcha/)
 * [Issues](http://github.com/matthutchinson/acts_as_textcaptcha/issues)
 * [Report a bug](http://github.com/matthutchinson/acts_as_textcaptcha/issues/new)
 * [Gem](http://rubygems.org/gems/acts_as_textcaptcha)
 * [GitHub](http://github.com/matthutchinson/acts_as_textcaptcha)
-
-## Who's who?
-
-* [ActsAsTextcaptcha](http://github.com/matthutchinson/acts_as_textcaptcha) and [little robot drawing](http://www.flickr.com/photos/hiddenloop/4541195635/) by [Matthew Hutchinson](http://matthewhutchinson.net)
-* [TextCaptcha](http://textcaptcha.com) API and service by [Rob Tuley](https://twitter.com/robtuley)
-
-## Usage
-
-This gem is used in a number of production websites and apps. It was originally
-extracted from code developed for [Bugle](http://bugleblogs.com). If you're
-happily using acts_as_textcaptcha in production, please let me know and I'll add
-you to this list!
-
-* [matthewhutchinson.net](http://matthewhutchinson.net)
-* [pmFAQtory.com](http://pmfaqtory.com)
-* [The FAQtory](http://faqtoryapp.com)
-* [DPT Watch, San Francisco](http://www.dptwatch.com)