Make webrick dependency optional

CHANGELOG.md

@@ -7,6 +7,7 @@
 
 ### Changed
 - `Ferrum::PendingConnectionsError` and `Ferrum::TimeoutError` were swallowed even though happening when traffic iterator results in empty array. [#583]
+- `webrick` is no longer a runtime dependency. It is only required by `Ferrum::Proxy`, so add `gem "webrick"` to your Gemfile if you use it.
 
 ### Fixed
 - Full-page screenshots no longer resize the window, preventing focus steal on macOS [#580]
@@ -16,6 +17,7 @@
 - `Ferrum::Page#idling?` no longer blocks on `loading="lazy"` iframes that Chrome never starts loading [#583]
 
 ### Removed
+- `webrick` runtime dependency dropped from the gemspec. `Ferrum::Proxy` still needs it, so add `gem "webrick"` to your Gemfile if you use the proxy server.
 
 
 ## [0.17.2](https://github.com/rubycdp/ferrum/compare/v0.17.1...v0.17.2) (March 23, 2026) ##

Gemfile

@@ -17,6 +17,7 @@ gem "rspec-wait"
 gem "rubocop", "~> 1.22"
 gem "rubocop-rake", require: false
 gem "sinatra", "~> 4.0"
+gem "webrick", "~> 1.7", require: false
 gem "yard", "~> 0.9", require: false
 
 gemspec

docs/9-proxy.md

@@ -33,3 +33,22 @@ browser.create_page(proxy: { host: "y.y.y.y", port: 31337, user: "user", passwor
   page.body # => "y.y.y.y"
 end
 ```
+
+## Built-in proxy server
+
+Ferrum also ships a small forwarding proxy server, `Ferrum::Proxy`, which is handy
+for tests or when you need to rotate upstream proxies at runtime:
+
+```ruby
+require "ferrum/proxy"
+
+proxy = Ferrum::Proxy.start(host: "127.0.0.1", port: 0)
+browser = Ferrum::Browser.new(proxy: { host: proxy.host, port: proxy.port })
+```
+
+`Ferrum::Proxy` is built on top of [`webrick`](https://rubygems.org/gems/webrick),
+which is **not** a dependency of Ferrum. If you use it, add webrick to your Gemfile:
+
+```ruby
+gem "webrick"
+```

ferrum.gemspec

@@ -28,6 +28,5 @@ Gem::Specification.new do |s|
   s.add_dependency "addressable",      "~> 2.5"
   s.add_dependency "base64",           "~> 0.2"
   s.add_dependency "concurrent-ruby",  "~> 1.1"
-  s.add_dependency "webrick",          "~> 1.7"
   s.add_dependency "websocket-driver", "~> 0.7"
 end

lib/ferrum/browser.rb

@@ -3,7 +3,6 @@
 require "base64"
 require "forwardable"
 require "ferrum/page"
-require "ferrum/proxy"
 require "ferrum/client"
 require "ferrum/contexts"
 require "ferrum/browser/xvfb"

lib/ferrum/proxy.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
 require "tempfile"
-require "webrick"
-require "webrick/httpproxy"
+
+begin
+  require "webrick"
+  require "webrick/httpproxy"
+rescue LoadError
+  warn("Please add webrick to your Gemfile to use Ferrum proxy")
+  raise
+end
 
 module Ferrum
   class Proxy

spec/browser_spec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "ferrum/proxy"
+
 describe Ferrum::Browser do
   describe "#new" do
     let(:logger) { StringIO.new }