HttpMimic 🎭

gem 'http_mimic'

require 'http_mimic'

# Check if driver is installed locally
HttpMimic.driver_installed? # => true / false

# Manually trigger download (defaults to latest stable release v2.1.1)
HttpMimic.download_driver!

# Specify a version or force re-download
HttpMimic.download_driver!(version: 'v2.1.1', force: true)

# List all available browser binary names installed locally
HttpMimic::Downloader.available_binaries
# => ["curl_chrome131", "curl_chrome120", "curl_firefox135", "curl_safari180", ...]

require 'http_mimic'

# Send a GET request (simulates Chrome 131 fingerprint by default)
response = HttpMimic.get(
  'https://tls.browserleaks.com/json',
  impersonate: 'chrome131'
)

puts response.code                    # => 200
puts response.success?                 # => true
puts response['ja3_hash']             # => Authentic Chrome 131 JA3 fingerprint
puts response.headers['content-type'] # => "application/json"

# Send a POST JSON request (simulating Safari 18.0)
response = HttpMimic.post(
  'https://httpbin.org/post',
  json: { name: 'Alice', role: 'admin' },
  impersonate: 'safari180'
)

puts response.code            # => 200
puts response['json']['name'] # => "Alice"

class BrowserLeaksClient
  include HttpMimic

  base_uri 'https://tls.browserleaks.com'
  impersonate 'chrome120' # Default to Chrome 120
  default_timeout 30
  headers 'Accept-Language' => 'en-US,en;q=0.9'

  def test_fingerprint
    get('/json')
  end
end

client = BrowserLeaksClient.new
res = client.test_fingerprint

puts "HTTP Status: #{res.code}"
puts "JA3 Hash: #{res['ja3_hash']}"
puts "User-Agent: #{res['user_agent']}"

client = HttpMimic::Client.new(
  base_uri: 'https://api.example.com',
  mode: :auto,
  impersonate: 'firefox135',
  timeout: 15,
  headers: {
    'X-API-KEY' => 'my_api_key'
  }
)

# Execute GET
response = client.get('/v1/users', query: { limit: 10 })

# Execute POST
response = client.post('/v1/users', json: { username: 'bob' })

# 1. No-Brain Auto Mode (Works automatically for Cloudflare, Akamai, etc.):
response = HttpMimic.get('https://www.adidas.com.hk/en/KI8139.html')
puts response.code                 # => 200
puts response.mode_used            # => :android
puts response.fallback_triggered?  # => true

# 2. Extract images and metadata with built-in helpers:
puts response.title                # => "SAMBA OG SHOES - Brown | adidas Hong Kong"
images = response.extract_images   # => ["https://assets.adidas.com/images/.../KI8139_01_00_standard.jpg", ...]

# 3. Fetch and save binary images directly:
HttpMimic.get(images.first).save('samba_og.jpg')

# 1. Enable per-request
response = HttpMimic.get('https://example.com/items', persist_cookies: true)

# 2. Or enable in class mixin
class Scraper
  include HttpMimic
  persist_cookies true
  # persist_on_failure false # (default: do not save cookies on 403 / verification failure)
  # clear_on_failure true    # (default: auto-clear cached cookies if verification fails)
end

# 3. Manual CookieStore helpers
HttpMimic.load_cookies('example.com')                  # => Hash of active cookies
HttpMimic.save_cookies('example.com', { session: '123' }) # Save cookies with default TTL
HttpMimic.clear_cookies!('example.com')                # Clear host or all cookies

HttpMimic.configure do |config|
  # Multi-strategy & Smart Fallback
  config.mode                    = :auto       # :auto (default), :impersonate_first, :curl_first, :impersonate_only, :curl_only
  config.auto_fallback           = true        # Automatically retry with alternative profile if blocked
  config.retry_statuses          = [403, 429, 503] # Status codes that trigger auto-fallback

  # Browser simulation & request defaults
  config.default_impersonate     = 'chrome131' # Default browser target
  config.default_timeout         = 30          # Request timeout (seconds)
  config.default_connect_timeout = 10          # Connection timeout (seconds)
  config.follow_redirects        = true        # Automatically follow 3xx redirects
  config.max_redirects           = 10          # Maximum redirect limit
  config.fallback_to_curl        = true        # Fall back to system curl if binary is missing
  config.raise_on_error          = false       # Raise exceptions on HTTP errors / non-zero exits
  config.debug                   = false       # Print debug logs

  # Navigation headers & Client Hints simulation (enabled by default)
  config.navigation_headers      = true        # Browser-accurate sec-ch-ua, sec-fetch-*, Accept headers

  # Host CookieStore Persistence (disabled by default)
  config.persist_cookies         = false                                     # Auto-persist cookies per host
  config.cookie_store_dir        = File.expand_path('~/.http_mimic/cookies') # Directory for cookie store
  config.persist_on_failure      = false                                     # Do not save cookies if request/verification fails
  config.clear_on_failure        = true                                      # Purge cached host cookies on 403 / verification failure

  # WAF challenge solving (enabled by default)
  config.auto_solve_waf          = true        # Automatically solve detected WAF JS challenges

  # Webdrivers-like auto-download settings (enabled by default)
  config.auto_download           = true                                  # Auto-download missing binary
  config.driver_version          = 'v2.1.1'                              # Target release version
  config.install_dir             = File.expand_path('~/.http_mimic/bin') # Directory for binaries
  config.github_repo             = 'lexiforest/curl-impersonate'         # GitHub source repository
end

# Auto-detects SPA shell and seamlessly renders with Obscura
response = HttpMimic.get('https://example.com/spa', auto_render_spa: true)

puts response.code    # => 200
puts response.title   # => Fully hydrated DOM title
puts response.body    # => Fully rendered HTML with client-side injected DOM nodes

# Direct SPA render
response = HttpMimic.render('https://example.com/spa')

# or via alias:
response = HttpMimic.spa('https://example.com/spa')

# Automatically obtain a proxy from the pool and execute request
response = HttpMimic.get('https://httpbin.org/ip', auto_proxy: true)

# Explicit proxy always takes precedence over auto_proxy:
response = HttpMimic.get('https://httpbin.org/ip', auto_proxy: true, proxy: 'http://my-dedicated-proxy:8080')

HttpMimic.configure do |config|
  config.auto_proxy = true          # Enable free proxy pool by default
  config.proxy_retries = 3          # Maximum proxy retry attempts on connection failure
  config.proxy_pool_ttl = 1800      # Cache duration for fetched proxy list (seconds)
end

# Or via class-level DSL:
HttpMimic.auto_proxy = true

# Check available pool size
HttpMimic.proxy_pool.size

# Sample a random proxy from the pool
HttpMimic.proxy_pool.sample # => "http://185.200.188.234:10001"

# Manually refresh the proxy pool
HttpMimic.refresh_proxies!

# Load custom proxies into the pool
HttpMimic.proxy_pool.load(['http://1.2.3.4:8080', 'http://5.6.7.8:3128'])

response = HttpMimic.get('https://httpbin.org/get')

# Status information
response.code           # => 200 (Integer)
response.status         # => 200
response.status_message # => "OK"
response.http_version   # => "2"
response.success?       # => true (2xx)
response.redirect?      # => false (3xx)
response.client_error?  # => false (4xx)
response.server_error?  # => false (5xx)

# Response body & File operations
response.body           # => Raw Body (String / binary bytes)
response.binary?        # => true if content is an image, pdf, or binary stream
response.save('image.jpg') # => Directly saves response body to file
response.parsed_response# => Auto-parsed JSON Hash / Array
response['key']         # => Direct key access to parsed_response

# HTML & Scraping Helpers
response.title          # => HTML page title
response.og_image       # => OpenGraph image URL
response.meta_description # => Meta description
response.extract_images # => Array of all resolved image URLs in HTML

# Headers & Cookies
response.headers['content-type'] # => Case-insensitive header access
response.cookies['session_id']   # => Parsed Set-Cookie store
response.history                 # => Array of redirect history metadata

# Underlying execution & multi-strategy details
response.mode_used            # => :impersonate, :android, :ios, or :curl
response.fallback_triggered?  # => true if smart fallback was executed
response.attempts             # => Array of execution metadata for each attempt
response.exit_code            # => Process exit status (0 for success)
response.stderr               # => Stderr output from curl
response.command              # => Array of the exact CLI arguments executed