Skip to content

feat(timeout): bound calls by a single Deadline and unify the concurrency primitives - #707

Open
route wants to merge 16 commits into
mainfrom
feat/deadline
Open

route wants to merge 16 commits into
mainfrom
feat/deadline

Conversation

@route

@route route commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

What

Every call now runs under one Ferrum::Deadline instead of stacked per-step timeouts, and the waiting primitives are unified.

Timeouts

  • Ferrum::Deadline.within(seconds) { ... } bounds every call the block makes, go_to, cookies and evaluate included. It is thread-local, a nested block can only shorten the budget.
  • timeout: on go_to, refresh, back, forward, click and wait_for_navigation bounds the whole call, page load included. go_to, refresh and the script methods no longer restart the timeout for each step.
  • click, mouse.move, keyboard.type, back, forward, wait_for_selector and node scripts (evaluate, text, value, ...) share one timeout across the commands they send, they restarted it for each. A click that starts a navigation now counts finding and moving to the node against the same budget. slowmo and click(delay:) count too, raise timeout when using them.
  • client.command requires a timeout: and has no async: true, use client.notify to send without waiting. browser.command defaults to the browser's timeout.
  • :protocol_timeout is removed and ignored: internal commands use a fixed 5 second Client::PROTOCOL_TIMEOUT.
  • wait: of click is renamed to navigation_wait: (old keyword warns) and leaves page.command. Mouse::CLICK_WAIT and Page::GOTO_WAIT are merged into Page::NAVIGATION_WAIT / FERRUM_NAVIGATION_WAIT, the old env vars still work and warn.
  • Public methods that wait document @raise [TimeoutError], and the :timeout option text says what it bounds.

Concurrency

  • Ferrum::Concurrency::Cell and AwaitableMap replace IVar, MVar and Event. page.event is now page.idle.
  • Client::Subscriber becomes Ferrum::Concurrency::Dispatcher, generic over keys and lanes, with Client#dispatch choosing the lane. client.subscriber is now client.dispatcher.
  • browser.targets and context.targets return a snapshot copy.
  • The unused Concurrent::IVar / Event signatures are gone. concurrent-ruby stays, JRuby has no GVL and relies on its thread-safe collections.

Fixes

  • Pending targets no longer leak when a context is torn down.
  • A timed out wait_for_reload or Downloads#wait no longer forces the latch, which marked an in-flight download as finished.
  • Event callback ids survive another callback being removed.
  • FERRUM_DEFAULT_TIMEOUT keeps its fraction.
  • wait_for_selector returns nil at its timeout even when a poll is still running.

Breaking

client.command without timeout:, async: true, protocol_timeout, page.command(wait:), Mouse::CLICK_WAIT, Page::GOTO_WAIT, client.subscriber, and targets no longer following the live hash. Composite calls now share one timeout. All listed in the changelog.

Not covered

Calls that send several commands but are left on the page timeout per command: create_page, browser.reset, cookies.clear, resize, set_viewport, screenshot, pdf.

Testing

Full suite: 1326 examples, 0 failures, 4 pending. Rubocop clean. The new timeout specs fail without the fix.

route added 16 commits November 15, 2026 22:17
…eadline

Steps of one operation used to each get a fresh timeout, so go_to could take about twice the timeout (navigate
response, then load) and an evaluate restarted the clock on every retry. One Deadline is now created per public
call and every step reads what is left of it.

go_to, refresh and wait_for_navigation accept timeout:. refresh watches for the navigation to start for GOTO_WAIT
instead of the whole timeout.
…argets on Utils::AwaitableMap

Cell is one waitable slot (set, clear, close, wait with a Deadline, a generation counter) in place of the IVar
mailboxes, the MVar execution ids with their sentinel, and Utils::Event. Closing a cell wakes its waiters, so a
dead client releases the commands in flight.

Context keeps its targets in an AwaitableMap, so create_target waits for the key whichever of the command response
and the targetCreated event comes first. That removes the per-target mailboxes, and with them the leak for targets
nobody created. Context#targets returns a snapshot hash.
A command that skipped Page fell back to protocol_timeout without the call site saying so, so Cookies and browser
contexts followed it and not timeout. Client#command now needs timeout: unless it is async, and every caller states
its budget: Cookies use timeout, the Target.* bookkeeping uses protocol_timeout.

Browser#command, Worker#command and Target#command default to the object's timeout. Direct client.command calls
without timeout: raise ArgumentError.
…otifications without a timeout

Deadline.within(seconds) { ... } keeps a thread-local deadline, and Deadline.wrap returns whichever of the requested
and the ambient deadline expires first, so every call made in the block shares one budget without taking a new
argument. A nested block can only shorten it.

Client#command now needs timeout: and no longer takes async:. Client#notify and SessionClient#notify send a command
nobody waits for, with no deadline, so an expired block can't drop a Fetch.continueRequest frame. Creating pages and
contexts follows timeout instead of protocol_timeout.

Every public method that talks to Chrome documents that it can raise TimeoutError.
…s created with

remaining can come out a few nanoseconds above the seconds a deadline was started with, so the within specs compared
it to 0.05 and failed now and then. They only need to tell the bounded budget from the unbounded one.
…option

Internal bookkeeping calls and browser init no longer follow a user setting: Client::PROTOCOL_TIMEOUT (5 seconds) bounds
the background Target.* commands, and WebSocket::WRITE_TIMEOUT (30 seconds) the write watchdog. Page and context creation
follow timeout. :protocol_timeout is ignored, and Options#protocol_timeout, protocol_timeout=, their Browser delegates
and FERRUM_PROTOCOL_TIMEOUT are gone.
…ing for it times out

wait_for_reload and Downloads#wait cleared the idle cell to wait for the next signal and set it again whatever happened,
so a download still in progress when the timeout was reached looked finished. They now set it back only when nothing
cleared it meanwhile.
…removed

Subscriber#on returned the callback's index in the event's list and off deleted by index, so removing a callback shifted
every later one and a stale id removed the wrong callback or none. Ids now come from a counter and are never reused.
off on an event nobody subscribed to no longer raises.
The environment value went through to_i, so FERRUM_DEFAULT_TIMEOUT=0.5 became 0 while timeout: 0.5 worked. The default
is a float now.
wait: meant how long to watch for a navigation after a command, and sat next to timeout: in Page#command, which made
the two hard to tell apart, and a plain "send this CDP command" method had no business knowing about navigations.

It is navigation_wait: in Mouse#click and Node#click, where the old keyword still works and warns, and in the positional
argument of wait_for_navigation. Page#command no longer takes it: go_to, refresh, back, forward and the mouse wrap their
command in wait_for_navigation! instead. A caller of page.command(wait:) wraps it the same way. Worker#execution_id!
names its argument timeout, which is what it was.
…e, back and scripts send, add timeout: to back, forward and click
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant