Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
bdfd403
fix(browser): always attempt every quit cleanup stage
dima4p Nov 6, 2026
e9c856c
fix(client): force-close websocket when cleanup raises
dima4p Nov 6, 2026
02576d5
fix(process): isolate Chromium temporary files per browser
dima4p Nov 6, 2026
1f9e083
test(process): verify per-browser Chromium temp directory
dima4p Nov 6, 2026
5c574ae
test(browser): cover cleanup after quit failures
dima4p Nov 6, 2026
9d92458
test(client): cover websocket close failure cleanup
dima4p Nov 6, 2026
88f2ff6
docs: note browser cleanup fixes
dima4p Nov 6, 2026
75a13cc
test(process): avoid spawning or waiting for a fake browser pid
dima4p Nov 6, 2026
2200456
test(process): assert temp directory state directly
dima4p Nov 6, 2026
6bd9b83
fix: close websocket socket when reader reaches EOF
dima4p Nov 7, 2026
9dda53e
test: cover websocket cleanup after peer EOF
dima4p Nov 7, 2026
b0c0cf2
fix(browser): clean up unquit browsers on garbage collection
dima4p Nov 8, 2026
dc18bac
fix(browser): keep GC cleanup trap-safe
dima4p Nov 11, 2026
82a64f6
fix(websocket): add finalizer-safe socket close
dima4p Nov 11, 2026
b28e56d
fix(client): finish worker cleanup after socket finalization
dima4p Nov 11, 2026
594048a
docs(client): clarify finalizer and close methods
dima4p Nov 11, 2026
3478128
fix: keep killing process group when leader was reaped
dima4p Nov 12, 2026
84c7e96
test: cover already-reaped browser process leader
dima4p Nov 12, 2026
1bbbe93
test: align browser finalizer specs with socket-only cleanup
dima4p Nov 12, 2026
fd98af2
test: cover socket finalizer failure handling
dima4p Nov 12, 2026
68abc6e
test: simulate a genuinely reaped Chromium leader
dima4p Nov 12, 2026
5c11a81
Fix RuboCop offenses
Nov 14, 2026
88480d6
Capture expected GC cleanup warning in spec
Nov 14, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,11 @@
`go_to` instead

### Fixed
- Browser GC finalization closes the CDP socket without running thread or queue operations in finalizer context
- Unquit browsers close their CDP connections and stop their browser process when garbage-collected
- WebSocket connections now close their local socket and writer when the peer disconnects unexpectedly
- Chromium's Linux temporary files now live inside each browser's Ferrum user-data directory and are removed with it
- `Browser#quit` and `Client#close` continue cleanup when an earlier close step raises
- `AuthRequest#abort` raised `BrowserError` and left the page hanging, it cancels the auth challenge now
- `InterceptedRequest#navigation_request?` and `AuthRequest#navigation_request?` always returned `nil`, they are true
for document requests now
Expand Down
39 changes: 34 additions & 5 deletions lib/ferrum/browser.rb
Original file line number Diff line number Diff line change
Expand Up @@ -230,13 +230,23 @@ def restart
# The background cleanup thread when `wait: false`, `nil` otherwise.
#
def quit(wait: true)
return unless @client
return unless @client || @process

contexts&.close_connections

@client.close
thread = @process.stop(wait: wait)
ObjectSpace.undefine_finalizer(self)
client = @client
process = @process
contexts = @contexts
@client = @process = @contexts = nil

begin
contexts&.close_connections
ensure
begin
client&.close
ensure
thread = process&.stop(wait: wait)
end
end
thread
end

Expand Down Expand Up @@ -297,12 +307,31 @@ def start
@client = Client.new(@process.ws_url, options)
@options.default_user_agent = version.user_agent
@contexts = Contexts.new(@client)
ObjectSpace.define_finalizer(self, self.class.send(:finalizer, @client, @process))
rescue StandardError
@process.stop
raise
end
end

# The finalizer must not capture the Browser instance itself. Client#finalize
# only closes the socket; its reader and dispatch threads finish cleanup in
# their own thread contexts. Process#stop handles the local browser process.
def self.finalizer(client, process)
proc do
client&.finalize
rescue StandardError => e
warn("[Ferrum] GC cleanup: closing client socket failed: #{e.class}: #{e.message}")
ensure
begin
process&.stop
rescue StandardError => e
warn("[Ferrum] GC cleanup: stopping browser process failed: #{e.class}: #{e.message}")
end
end
end
private_class_method :finalizer

def debug_url
response = JSON.parse(Net::HTTP.get(URI(build_remote_debug_url(path: "/json"))))

Expand Down
8 changes: 8 additions & 0 deletions lib/ferrum/browser/process.rb
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,13 @@ def initialize(options)
@env = Hash(options.env)

@user_data_dir = Dir.mktmpdir("ferrum_user_data_dir_")
if Utils::Platform.platform_name == :linux
# Chromium uses TMPDIR for files such as its process-singleton
# socket. Keep them inside this browser's directory so stop can
# remove them without touching another browser's files.
@temp_dir = File.join(@user_data_dir, "tmp")
Dir.mkdir(@temp_dir)
end
@command = Command.build(options, @user_data_dir)
end

Expand Down Expand Up @@ -143,6 +150,7 @@ def spawn_browser(io)
process_options = { in: File::NULL, out: io, err: io }
process_options[:pgroup] = true unless Utils::Platform.windows?
env = Hash(@xvfb&.to_env).merge(@env)
env["TMPDIR"] = @temp_dir if @temp_dir

@pid = ::Process.spawn(env, *@command.to_a, process_options)
ObjectSpace.define_finalizer(self, Killer.finalizer([@pid, @xvfb&.pid], @user_data_dir))
Expand Down
15 changes: 12 additions & 3 deletions lib/ferrum/browser/process/killer.rb
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,16 @@ def kill(pid)
# renderer/zygote that ignores TERM. Reaping the leader must not
# by itself end the loop, or that child is orphaned forever
# since KILL is only ever sent from the timeout branch below.
leader_exited ||= !::Process.wait(pid, ::Process::WNOHANG).nil?
unless leader_exited
begin
leader_exited = !::Process.wait(pid, ::Process::WNOHANG).nil?
rescue Errno::ECHILD
# Another thread or a SIGCHLD handler may already have reaped
# the leader. The process group can still contain live Chrome
# children, so keep checking it and escalate to KILL if needed.
leader_exited = true
end
end
break if leader_exited && !process_group_alive?(pid)

sleep(WAIT_KILLED)
Expand All @@ -61,8 +70,8 @@ def kill(pid)
wait_reaped(pid) unless leader_exited
break
end
rescue Errno::ESRCH, Errno::ECHILD
# nop
rescue Errno::ESRCH
# The process and its group are already gone.
end

#
Expand Down
36 changes: 30 additions & 6 deletions lib/ferrum/client.rb
Original file line number Diff line number Diff line change
Expand Up @@ -293,6 +293,16 @@ def session(session_id)
SessionClient.new(self, session_id)
end

#
# Closes the socket without touching queues, locks or threads. Safe for
# Browser's GC finalizer; the reader/dispatch threads complete cleanup.
#
# @return [void]
#
def finalize
@ws.finalize
end

#
# Closes the underlying websocket, drops pending commands and stops
# the message-processing thread and subscriber.
Expand All @@ -301,11 +311,21 @@ def session(session_id)
#
def close
@ws.close
# Give a thread some time to handle a tail of messages
@pendings.clear
@thread.kill unless @thread.join(1)
@subscriber.close
@ws.force_close
ensure
begin
# Give a thread some time to handle a tail of messages
@pendings.clear
ensure
begin
@thread.kill unless @thread.join(1)
ensure
begin
@subscriber.close
ensure
@ws.force_close
end
end
end
end

#
Expand Down Expand Up @@ -355,7 +375,11 @@ def start
warn("Ferrum: dispatch stopped, #{e.class}: #{e.message}\n #{e.backtrace&.first}")
@ws.messages.close
ensure
release_pendings
begin
release_pendings
ensure
@subscriber.close
end
end
end

Expand Down
12 changes: 12 additions & 0 deletions lib/ferrum/client/web_socket.rb
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,16 @@ def close
#
# @return [void]
#
# Closes only the underlying socket. This deliberately avoids queues,
# mutexes and thread operations so it can be called from a GC finalizer.
# The reader and writer threads perform their normal queue cleanup when
# the socket close wakes them.
def finalize
@sock.close unless @sock.closed?
rescue IOError, SystemCallError
# The socket may already have been closed by either worker thread.
end

def force_close
@outgoing.close
@sock.close unless @sock.closed?
Expand Down Expand Up @@ -236,6 +246,8 @@ def start
warn("Ferrum: websocket reader stopped, #{e.class}: #{e.message}\n #{e.backtrace&.first}")
ensure
@messages.close
@outgoing.close
force_close
end
end

Expand Down
46 changes: 46 additions & 0 deletions spec/unit/browser/process/killer_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,52 @@ def reaped?(pid)
end

describe ".kill", if: Ferrum::Utils::Platform.mri? && !Ferrum::Utils::Platform.windows? do
it "still kills the process group when the leader was already reaped" do
child_pid_path = File.join(Dir.tmpdir, "ferrum-process-spec-reaped-child-#{Process.pid}")
script = <<~RUBY
pid = fork do
trap("TERM", "IGNORE")
sleep 30
end
Process.detach(pid)
File.write(#{child_pid_path.inspect}, pid.to_s)
sleep 30
RUBY
leader_pid = Process.spawn(RbConfig.ruby, "-e", script, pgroup: true)

begin
start = Ferrum::Utils::ElapsedTime.monotonic_time
sleep(0.05) until File.size?(child_pid_path) || Ferrum::Utils::ElapsedTime.timeout?(start, 5)
child_pid = File.read(child_pid_path).to_i

# Reap the leader for real while its detached child remains in the
# same process group. This reproduces ECHILD without stubbing wait.
Process.kill("TERM", leader_pid)
expect(Process.wait(leader_pid)).to eq(leader_pid)

described_class.kill(leader_pid)

start = Ferrum::Utils::ElapsedTime.monotonic_time
loop do
begin
Process.kill(0, child_pid)
rescue Errno::ESRCH
break
end
raise "process group child survived KILL" if Ferrum::Utils::ElapsedTime.timeout?(start, 5)

sleep(0.05)
end
ensure
begin
Process.kill("KILL", -leader_pid) if leader_pid
rescue Errno::ESRCH
nil
end
FileUtils.rm_f(child_pid_path)
end
end

it "kills the whole process group, not just the leader, when a group member ignores TERM" do
child_pid_path = File.join(Dir.tmpdir, "ferrum-process-spec-child-pid-#{Process.pid}")

Expand Down
24 changes: 23 additions & 1 deletion spec/unit/browser/process_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -77,11 +77,33 @@
process.stop
end

it "keeps Chromium temporary files inside the browser user data directory", if: Ferrum::Utils::Platform.platform_name == :linux do
process = described_class.new(Ferrum::Browser::Options.new)
user_data_dir = process.instance_variable_get(:@user_data_dir)
temp_dir = File.join(user_data_dir, "tmp")

expect(Dir.exist?(temp_dir)).to be true
expect(Process).to receive(:spawn) do |env, *|
expect(env["TMPDIR"]).to eq(temp_dir)
expect(env["LD_PRELOAD"]).to be_nil
5678
end
allow(Ferrum::Browser::Process::Killer).to receive(:kill)
allow_any_instance_of(described_class).to receive(:parse_ws_url)

process.start
process.stop

expect(Dir.exist?(user_data_dir)).to be false
ensure
process&.stop
end

it "passes env through to the browser process" do
allow(Process).to receive(:wait).and_return(nil)
allow(Ferrum::Client).to receive(:new).and_return(client)

allow(Process).to receive(:spawn).with({ "LD_PRELOAD" => "some.so" }, any_args).and_return(123_456_789)
allow(Process).to receive(:spawn).with(hash_including("LD_PRELOAD" => "some.so"), any_args).and_return(123_456_789)

allow_any_instance_of(Ferrum::Browser::Process).to receive(:parse_ws_url)

Expand Down
64 changes: 64 additions & 0 deletions spec/unit/browser_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,70 @@ def puts(*args)
end
end

describe "#quit" do
it "stops the process even when context cleanup raises" do
error = StandardError.new("context cleanup failed")
contexts = double(close_connections: true)
client = double(close: true)
process = double(stop: nil)
browser = described_class.allocate
browser.instance_variable_set(:@contexts, contexts)
browser.instance_variable_set(:@client, client)
browser.instance_variable_set(:@process, process)

allow(contexts).to receive(:close_connections).and_raise(error)

expect(client).to receive(:close)
expect(process).to receive(:stop).with(wait: true)

expect { browser.quit }.to raise_error(error)
expect(browser.client).to be_nil
expect(browser.process).to be_nil
expect(browser.contexts).to be_nil
end

it "stops the process even when client cleanup raises" do
error = StandardError.new("client cleanup failed")
contexts = double(close_connections: true)
client = double
process = double(stop: nil)
browser = described_class.allocate
browser.instance_variable_set(:@contexts, contexts)
browser.instance_variable_set(:@client, client)
browser.instance_variable_set(:@process, process)

allow(client).to receive(:close).and_raise(error)

expect(process).to receive(:stop).with(wait: true)

expect { browser.quit }.to raise_error(error)
end
end

describe "GC cleanup" do
it "closes the client socket and stops the process when finalized" do
client = double(finalize: true)
process = double(stop: nil)
finalizer = described_class.send(:finalizer, client, process)

expect(client).to receive(:finalize)
expect(process).to receive(:stop)
finalizer.call
end

it "stops the process even when closing the client socket raises" do
client = double
process = double(stop: nil)
allow(client).to receive(:finalize).and_raise(StandardError, "socket cleanup failed")
finalizer = described_class.send(:finalizer, client, process)

expect(process).to receive(:stop)
expect { finalizer.call }.to output(
"[Ferrum] GC cleanup: closing client socket failed: StandardError: socket cleanup failed\n"
).to_stderr
end
end

describe "#restart" do
it "restarts a browser whose previous start died after the client was built" do
browser = Ferrum::Browser.new
Expand Down
27 changes: 27 additions & 0 deletions spec/unit/client/web_socket_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,33 @@ def peak_concurrent_writes = @peak.value
web_socket.instance_variable_set(:@encoded, [])
end

describe "reader cleanup" do
it "closes the socket and writer when the peer closes the connection" do
socket, peer = Socket.pair(:UNIX, :STREAM, 0)
messages = Queue.new
outgoing = Queue.new
web_socket.instance_variable_set(:@sock, socket)
web_socket.instance_variable_set(:@messages, messages)
web_socket.instance_variable_set(:@outgoing, outgoing)

web_socket.send(:start_writer)
web_socket.send(:start)
reader = web_socket.instance_variable_get(:@thread)
writer = web_socket.instance_variable_get(:@writer)

peer.close

expect(reader.join(1)).to eq(reader)
expect(writer.join(1)).to eq(writer)
expect(socket).to be_closed
expect(messages).to be_closed
expect(outgoing).to be_closed
ensure
peer&.close unless peer&.closed?
socket&.close unless socket&.closed?
end
end

describe "#send_message" do
it "hands the driver the message as JSON" do
web_socket.send_message(id: 1)
Expand Down
Loading
Loading