private-captcha-ruby
Ruby client for server-side verification of Private Captcha solutions.
Installation
Add this line to your application's Gemfile:
gem 'private_captcha'And then execute:
bundle installOr install it yourself as:
gem install private_captchaQuick Start
require 'private_captcha'
# Initialize the client with your API key
client = PrivateCaptcha::Client.new do |config|
config.api_key = 'your-api-key-here'
end
# Verify a captcha solution
begin
result = client.verify('user-solution-from-frontend')
if result.success
puts 'Captcha verified successfully!'
else
puts "Verification failed: #{result.error_message}"
end
rescue PrivateCaptcha::Error => e
puts "Error: #{e.message}"
endUsage
Web Framework Integration
Sinatra Example
require 'sinatra'
require 'private_captcha'
client = PrivateCaptcha::Client.new do |config|
config.api_key = 'your-api-key'
end
post '/submit' do
begin
# Verify captcha from form data
client.verify_request(request)
# Process your form data here
'Form submitted successfully!'
rescue PrivateCaptcha::Error
status 400
'Captcha verification failed'
end
endRails Example
class FormsController < ApplicationController
def submit
client = PrivateCaptcha::Client.new do |config|
config.api_key = 'your-api-key'
end
begin
client.verify_request(request)
# Process form data
render plain: 'Success!'
rescue PrivateCaptcha::Error
render plain: 'Captcha failed', status: :bad_request
end
end
endRack Middleware
require 'private_captcha'
use PrivateCaptcha::Middleware,
api_key: 'your-api-key',
failed_status_code: 403Configuration
Client Options
require 'private_captcha'
client = PrivateCaptcha::Client.new do |config|
config.api_key = 'your-api-key'
config.domain = PrivateCaptcha::Configuration::EU_DOMAIN # replace domain for self-hosting or EU isolation
config.form_field = 'private-captcha-solution' # custom form field name
config.max_backoff_seconds = 20 # maximum wait between retries
config.attempts = 5 # number of retry attempts
config.logger = Logger.new(STDOUT) # optional logger
endNon-standard backend domains
require 'private_captcha'
# Use EU domain
eu_client = PrivateCaptcha::Client.new do |config|
config.api_key = 'your-api-key'
config.domain = PrivateCaptcha::Configuration::EU_DOMAIN # api.eu.privatecaptcha.com
end
# Or specify custom domain in case of self-hosting
custom_client = PrivateCaptcha::Client.new do |config|
config.api_key = 'your-api-key'
config.domain = 'your-custom-domain.com'
endRetry Configuration
result = client.verify(
'solution',
max_backoff_seconds: 15, # maximum wait between retries
attempts: 3 # number of retry attempts
)Requirements
- Ruby 3.0+
- No external dependencies (uses only standard library)
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
For issues with this Ruby client, please open an issue on GitHub. For Private Captcha service questions, visit privatecaptcha.com.