What does the code do?

The gem contains two main parts, a module for ActiveRecord models, and a single view helper method. The ActiveRecord module also makes use of TextcaptchaApi and TextcaptchaCache.

A call to @model.textcaptcha in your controller will query the TextCaptcha web service. A GET request is made (via Net::HTTP) and parsed with JSON. A textcaptcha_question and a random cache key are assigned to the record. An array of possible answers are stored in the TextcaptchaCache with this random key (by default cached answers have a 10 minute TTL). If your forms take more than 10 minutes to complete you can adjust this value by setting the cache_expiry_minutes option.

NOTE: Internally TextcaptchaCache directly wraps Rails.cache and all cache keys are name spaced.

On saving, validate_textcaptcha is called on @model.validate checking that the @model.textcaptcha_answer matches any 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. Answer checking is case-insensitive and trailing/leading white-space is 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 assigned. After one correct answer, the answer and a mutating key are sent on all future 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 from your config options. If the web service fails or no API key is specified AND no fallback questions are configured, TextCaptcha checking is disabled and the model will pass as valid.