From f6a5ce55e5421cfeb6b7f258305bdd80a227988f Mon Sep 17 00:00:00 2001
From: Oli Peate <oliver.peate@char.gy>
Date: Mon, 6 Jul 2026 16:45:34 +0100
Subject: [PATCH] Make webrick dependency optional

Only required when Ferrum::Proxy is used
---
 CHANGELOG.md          |  2 ++
 Gemfile               |  1 +
 docs/9-proxy.md       | 19 +++++++++++++++++++
 ferrum.gemspec        |  1 -
 lib/ferrum/browser.rb |  1 -
 lib/ferrum/proxy.rb   | 10 ++++++++--
 spec/browser_spec.rb  |  2 ++
 7 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d547674e..aa5f73f7 100644
--- a/CHANGELOG.md
+++ b/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) ##
diff --git a/Gemfile b/Gemfile
index 738bbc05..94f47516 100644
--- a/Gemfile
+++ b/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
diff --git a/docs/9-proxy.md b/docs/9-proxy.md
index 50c1bace..6dc1501f 100644
--- a/docs/9-proxy.md
+++ b/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"
+```
diff --git a/ferrum.gemspec b/ferrum.gemspec
index ff017107..1f693125 100644
--- a/ferrum.gemspec
+++ b/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
diff --git a/lib/ferrum/browser.rb b/lib/ferrum/browser.rb
index d131d8f1..3efc2ddb 100644
--- a/lib/ferrum/browser.rb
+++ b/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"
diff --git a/lib/ferrum/proxy.rb b/lib/ferrum/proxy.rb
index 13049bc0..59e409c3 100644
--- a/lib/ferrum/proxy.rb
+++ b/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
diff --git a/spec/browser_spec.rb b/spec/browser_spec.rb
index 41eab418..6d4c18da 100644
--- a/spec/browser_spec.rb
+++ b/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 }