captched_to_death 0.2.0

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+*.rvmrc
+.bundle
+.DS_Store
+Gemfile.lock
+doc/
+pkg/*

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - "1.9.2"
+  - "1.9.3"

data/DeathByCaptcha.txt

@@ -0,0 +1,47 @@
+Hi Captcha Killers,
+
+ For security and stability reasons, we’ve decided to change our domain
+ name. The new domain name will be http://deathbycaptcha.eu. This
+ change will allow us to keep operating our service securely. Our
+deathbycaptcha.com domain will close in April.
+
+ We’re also changing our API server domain. The API server domain is
+ the one used by your software to send CAPTCHAs to our service. There’s
+ a small minority of software that require you to manually input some
+ Host or API details. Please find below instructions on how to identify
+ if your software requires manual changes, and how to make changes to
+ the configuration if needed:
+
+ * For software that doesn’t have an API (or Host) URL settings textbox:
+ ** Don’t do anything! We’ve already informed most software vendors
+ about the API update :)
+
+ *For Software that asks for the DeathByCaptcha HTTP API:
+ ** host: http://api.dbcapi.me/api
+
+ * For software that uses the Decaptcher POST URL:
+ ** host: http://api.dbcapi.me/decaptcher
+
+ * For all other software, scripts or tools:
+ ** host: api.dbcapi.me
+
+ Please notice that these changes must to be in place by the first week
+ of April 2012 the latest.
+
+ Are you a software vendor and you haven’t heard anything from us? Send
+ us an email! All of our API Clients are updated with these new
+ settings.
+
+ We would like this information to be known only to our users and not
+ the rest of the internet. Please avoid sharing the new API details
+ publicly. We trust you guys!
+
+ On the other hand, we do encourage you to inform all of your fellow
+ captcha killers about our new website domain name:
+http://deathbycaptcha.eu
+
+ Happy Captcha Killing,
+ Jose M
+ Death By Captcha
+
+http://pastebin.com/ns9xKuqi

data/Gemfile

@@ -0,0 +1,4 @@
+source :rubygems
+
+# Specify your gem's dependencies in captched_to_death.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Cristian R. Arroyo
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,85 @@
+= CaptchedToDeath
+
+{<img src="https://travis-ci.org/vivaserver/captched_to_death.png" />}[https://travis-ci.org/vivaserver/captched_to_death]
+{<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/vivaserver/captched_to_death]
+
+CaptchedToDeath is a simple HTTP client for the DeathByCaptcha API written in Ruby. Note that while the DeathByCaptcha service supports both a HTTP API and a Sockets API, this library supports only the former.
+
+By default, all successful CaptchedToDeath responses are JSON-formatted. This cannot be changed yet.
+
+== Usage
+
+Some actions require a valid DeathByCaptcha user account credentials, name and password. Some requests to the API will be rejected if they're not provided. Note that also a CaptchedToDeath::NoCreditError exception will be raised if the account has no more credits left on it's balance.
+
+=== CaptchedToDeath::Client
+
+Initialization of the client can be done in many ways. Beginning with the simplest:
+
+    client = CaptchedToDeath::Client.new
+
+Pass the user credentials if you want to decode some CAPTCHA challenges with the remaining credits on your balance.
+
+    client = CaptchedToDeath::Client.new('username','password')
+
+Pass a block if you want to set the verbose option, that enables RestClient responses logging (only to STDOUT).
+
+    client = CaptchedToDeath::Client.new do |c|
+      c.username = 'username'
+      c.password = 'password'
+      c.verbose  = true
+    end
+
+=== Balance checking
+
+With your client initialized using you account credentials, you can check your current balance like so:
+
+    client.balance
+    => {"is_banned"=>false, "status"=>0, "rate"=>0.139, "balance"=>672.204, "user"=>99999}
+
+Note that the "balance" in the response means your cents left.
+
+=== CAPTCHA decoding
+
+With your client initialized using you account credentials, you can decode a CAPTCHA challenge if you still have credits left on your account. To do do so, just pass the CAPTCHA image URL:
+
+    client.decode('http://i.imgur.com/iWlb4.png')
+    => {"status"=>0, "captcha"=>36923242, "is_correct"=>true, "text"=>"jd472tfo"}
+
+Note that only GIF, JPEG and PNG are supported as valid CAPTCHA challenges. Also, the response time depends on the current DeathByCaptcha server load.
+
+=== CAPTCHA status checking
+
+Once the challenge has already been accepted, it's status can be checked at any time using it's CAPTCHA ID.
+
+    client.captcha(36723349)
+    => {"status"=>0, "captcha"=>36723349, "is_correct"=>true, "text"=>"jd472tfo"}
+
+=== CAPTCHA reporting
+
+If you think the result of the challenge decoding is not correct you can report it to get a refund. But mind that you have to report it within the hour of submitting it and that abusing this feature might get you banned.
+
+    client.report(36723349)
+    => {"status"=>0, "captcha"=>36723349, "is_correct"=>false, "text"=>"jd472tfo"}
+
+=== DeathByCaptcha server status checking
+
+You can check the current status of the DeathByCaptcha server to find out the average decoding time at any particular moment. This time will directly affect the response time of any decoding you submit afterwards.
+
+   CaptchedToDeath::Server.status
+   => {"status"=>0, "todays_accuracy"=>0.890402, "solved_in"=>13, "is_service_overloaded"=>false}
+
+== Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+== License
+
+CaptchedToDeath is released under the {MIT License}[http://www.opensource.org/licenses/MIT].
+
+== Copyright
+
+Copyright (c)2012 {Cristian R. Arroyo}[mailto:cristian.arroyo@vivaserver.com]

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+# ref: http://rpheath.com/posts/394-get-the-most-out-of-test-unit
+# ref: http://stackoverflow.com/a/8395163
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'spec'
+  t.verbose = false
+  t.pattern = 'spec/*_spec.rb'
+end
+
+task :default => :test

data/captched_to_death.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "captched_to_death/version"
+
+Gem::Specification.new do |s|
+  s.name        = "captched_to_death"
+  s.version     = CaptchedToDeath::VERSION
+  s.authors     = ["Cristian R. Arroyo"]
+  s.email       = ["cristian.arroyo@vivaserver.com"]
+  s.homepage    = "https://github.com/vivaserver/captched_to_death"
+  s.summary     = %q{A simple HTTP client to DeathByCaptcha API}
+  s.description = %q{A simple HTTP client to DeathByCaptcha API using just RestClient}
+
+  s.add_runtime_dependency 'rest-client', "~> 1.6"
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'rake'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+end

data/lib/captched_to_death/client.rb

@@ -0,0 +1,132 @@
+require 'base64'
+require 'logger'
+
+module CaptchedToDeath
+  class Client
+    attr_writer :username, :password, :accept, :verbose
+
+    # Sensible defaults that can be overriden by configuration block:
+    #
+    #   client = CaptchedToDeath::Client.new do |c|
+    #     c.username = 'username'
+    #     c.password = 'password'
+    #     c.verbose  = true
+    #   end
+    #
+    # or just:
+    #
+    #   client = CaptchedToDeath::Client.new('username','password')
+    #
+    def initialize(*credentials)
+      @accept  = :json
+      @verbose = false
+      if credentials.size == 2
+        @username = credentials[0].to_s
+        @password = credentials[1].to_s
+      end
+      yield self if block_given?
+
+      RestClient.log = Logger.new(STDOUT) if @verbose
+    end
+
+    # User credit balance, includes account details.
+    #
+    def balance
+      fail RejectedError if empty_credentials?
+      response = RestClient.post "#{API_URI}/user", {:username => @username, :password => @password}, :accept => @accept
+      fail ServiceError unless response.code == 200
+      JSON.parse(response) 
+    end
+
+    # Polls for uploaded CAPTCHA status.
+    # You don't have to supply your Death by Captcha credentials this time.
+    # Please don't poll for a CAPTCHA status more than once in a couple of seconds.
+    # This is considered abusive and might get you banned.
+    #
+    def captcha(captcha_id)
+      response = RestClient.get "#{API_URI}/captcha/#{captcha_id}", {:accept => @accept}
+      JSON.parse(response)
+    rescue RestClient::Exception => e
+      case e.http_code
+      when 404
+        fail NotFound 
+      #503 (Service Temporarily Unavailable) when our service is overloaded (usually around 3:00–6:00 PM EST)
+      when 503  
+        # not sure 503 is ever sent, but retry if it is
+        sleep Server.status['solved_in']
+        retry
+      else
+        raise e
+      end
+    end
+
+    # Solving a CAPTCHA using Death by Captcha HTTP API requires performing at least two steps.
+    #
+    def decode(challenge_url, referer=nil, agent=nil)
+      fail RejectedError if empty_credentials?
+
+      response = RestClient.post "#{API_URI}/captcha", {
+        :username    => @username,
+        :password    => @password,
+        :captchafile => captcha_file(challenge_url,referer,agent)
+      }, :accept => @accept
+      resolved = JSON.parse(response) 
+      begin
+        sleep Server.status['solved_in']
+        resolved = captcha(resolved['captcha'])
+      end while resolved['text'].empty?
+      resolved
+    rescue RestClient::Exception => e
+      case e.http_code
+      #303 (See Other) CAPTCHA successfully uploaded: Location HTTP header will point to the status page
+      when 303
+        # RestClient: for result code 303 the redirection will be followed and the request transformed into a get
+        # (...so it'll be returned as a 200)
+      #403 (Forbidden) credentials were rejected, or you don't have enough credits
+      when 403
+        # TODO: discrimate wrong credentials
+        fail NoCreditError
+      #400 (Bad Request) if your request was not following the specification or not a valid image
+      when 400
+        fail RejectedError
+      #500 (Internal Server Error)
+      #503 (Service Temporarily Unavailable) when our service is overloaded (usually around 3:00–6:00 PM EST)
+      when 500, 503  
+        fail ServiceError, e.http_body
+      else
+        raise e
+      end
+    end
+
+    # Reports incorrectly solved CAPTCHAs.
+    # If you think your CAPTCHA was solved incorrectly, report it to Death by Captcha to get your money back.
+    # You'll get refunded if the CAPTCHA was uploaded less than an hour ago.
+    #
+    def report(captcha_id)
+      fail RejectedError if empty_credentials?
+
+      response = RestClient.post "#{API_URI}/captcha/#{captcha_id}/report", {
+        :username => @username,
+        :password => @password,
+      }, :accept => @accept
+
+      JSON.parse(response) 
+    end
+
+    private
+
+    def captcha_file(challenge_url, referer, agent)  #:nodoc:
+      file = RestClient.get challenge_url, {'Referer' => referer, 'User-Agent' => agent}
+      if file =~ TYPE_EXIF || file =~ TYPE_JFIF || file =~ TYPE_GIF || file =~ TYPE_PNG 
+        'base64:'+Base64.encode64(file)
+      else
+        raise RejectedError
+      end
+    end
+
+    def empty_credentials?  #:nodoc:
+      return true if @username.to_s.empty? || @password.to_s.empty?
+      false
+    end
+  end
+end

data/lib/captched_to_death/server.rb

@@ -0,0 +1,10 @@
+module CaptchedToDeath
+  class Server
+    # Current server status
+    def self.status
+      response = RestClient.get "#{API_URI}/status", :accept => :json
+      fail ServiceError unless response.code == 200
+      JSON.parse(response) 
+    end
+  end
+end

data/lib/captched_to_death/version.rb

@@ -0,0 +1,3 @@
+module CaptchedToDeath
+  VERSION = '0.2.0'
+end

data/lib/captched_to_death.rb

@@ -0,0 +1,33 @@
+require 'json'
+require 'rubygems'
+require 'bundler/setup'
+require 'rest_client'
+
+module CaptchedToDeath
+  # The base URI for the new DeathByCaptcha API. See DeathByCaptcha.txt
+  API_URI = 'http://api.dbcapi.me/api'
+
+  # Exception for insufficient user credits
+  class NoCreditError < StandardError; end
+
+  # Exception for unexisting CAPTCHA on status retreiving
+  class NotFound < StandardError; end
+
+  # Exception for missing/wrong user credentials; invalid captcha challenge
+  class RejectedError < StandardError; end
+
+  # Exception for server overloaded outage
+  class ServiceError < StandardError; end
+
+  # RegExps stolen from http://github.com/dim/ruby-imagespec
+  # see related blog post at http://boonedocks.net/mike/archives/162-Determining-Image-File-Types-in-Ruby.html
+  #
+  TYPE_EXIF = /^\xff\xd8\xff\xe1(.*){2}Exif/
+  TYPE_JFIF = /^\xff\xd8\xff\xe0\x00\x10JFIF/
+  TYPE_GIF  = /^GIF8/
+  TYPE_PNG  = /^\x89PNG/
+end
+
+require "captched_to_death/client"
+require "captched_to_death/server"
+require "captched_to_death/version"

data/spec/client_spec.rb

@@ -0,0 +1,79 @@
+require_relative 'spec_helper'
+require 'minitest/mock'
+
+describe CaptchedToDeath::Client do
+  before do
+    @username = ENV['DECAPTCHER_USERNAME']
+    @password = ENV['DECAPTCHER_PASSWORD']
+
+    # some CAPTCHA challenges for testing purposes:
+    # http://i.imgur.com/vOj5f.jpg (jd472tFO)
+    # http://i.imgur.com/iWlb4.png
+    # http://i.imgur.com/LsbEV.gif
+    # http://i.imgur.com/9a1da.jpg (jFnq60dd) 
+    # http://i.imgur.com/nRITM.jpg (ByKBPX9Z)
+    # http://i.imgur.com/mr3E0.jpg (6gOFiI01)
+    # http://i.imgur.com/uY3RN.jpg (gTKDrGtF)
+    @challenge = 'http://i.imgur.com/vOj5f.jpg'
+  end
+
+  it 'is the correct way of using mocks' do
+    client = MiniTest::Mock.new
+    response = {"captcha" => 123456789, "is_correct" => true, "text" => "jd472tFO"}
+
+    client.expect :captcha, response, [123456789]
+    client.captcha(123456789).must_equal response
+    assert client.verify
+
+    client.expect :decode, response, [@challenge]
+    client.decode(@challenge).must_equal response
+    assert client.verify
+  end
+
+  describe 'when checking balance' do
+    subject do
+      CaptchedToDeath::Client.new(@username,@password)
+    end
+
+    it 'responds with account details or does not work if missing API credentials' do
+      if @username && @password
+        balance = subject.balance
+        balance.must_be_instance_of Hash
+        balance.keys.must_equal ["is_banned", "status", "rate", "balance", "user"]  # NOTE: "balance" float means Cents
+        refute balance["is_banned"]
+      else
+        proc { subject.balance }.must_raise CaptchedToDeath::RejectedError
+      end
+    end
+  end
+
+  describe 'when polling for uploaded CAPTCHA status' do
+    subject do
+      CaptchedToDeath::Client.new
+    end
+
+    it 'raises custom exception on unexisting CAPTCHA id' do
+      proc { subject.captcha(:captcha_id) }.must_raise CaptchedToDeath::NotFound
+    end
+  end
+
+  describe 'when decoding challenges' do
+    subject do
+      CaptchedToDeath::Client.new
+    end
+
+    it 'does not work if missing API credentials' do
+      proc { subject.decode(@challenge) }.must_raise CaptchedToDeath::RejectedError
+    end
+  end
+
+  describe 'when reporting wrongly resolved captchas' do
+    subject do
+      CaptchedToDeath::Client.new
+    end
+
+    it 'does not work if missing API credentials' do
+      proc { subject.report(:captcha_id) }.must_raise CaptchedToDeath::RejectedError
+    end
+  end
+end

data/spec/server_spec.rb

@@ -0,0 +1,10 @@
+require_relative 'spec_helper'
+
+describe CaptchedToDeath::Server do
+  it 'checks for remote server status' do
+    status = CaptchedToDeath::Server.status
+    status.must_be_instance_of Hash
+    status.keys.must_equal ["status", "todays_accuracy", "solved_in", "is_service_overloaded"]
+    # NOTE: status["solved_in"] integer means Seconds
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require_relative '../lib/captched_to_death'
+require 'minitest/autorun'
+

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: captched_to_death
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
+platform: ruby
+authors:
+- Cristian R. Arroyo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-19 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: &72562580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: *72562580
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &72562370 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *72562370
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &72562140 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *72562140
+description: A simple HTTP client to DeathByCaptcha API using just RestClient
+email:
+- cristian.arroyo@vivaserver.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- DeathByCaptcha.txt
+- Gemfile
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- captched_to_death.gemspec
+- lib/captched_to_death.rb
+- lib/captched_to_death/client.rb
+- lib/captched_to_death/server.rb
+- lib/captched_to_death/version.rb
+- spec/client_spec.rb
+- spec/server_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/vivaserver/captched_to_death
+licenses: []
+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: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A simple HTTP client to DeathByCaptcha API
+test_files: []