Expose AbortSignal of the request timeout via context

[janbuchar]

• related to Reconsider timeout/cancellation implementation #3111 — which declined the ambitious version (replacing @apify/timeout wholesale) as not planned; this is the small one
• related to feat: redesign request timeouts and allow per-route overrides #3860 (per-phase timeout redesign), v4: add AbortSignal option to the BaseHttpClient interface #3456 (AbortSignal in SendRequestOptions)
• additive, non-breaking

Why

tryCancel() is a synchronous signal.aborted read — it cannot interrupt a pending await. So on a handler timeout, await fetch(url) (or sendRequest, or a DB call) runs to completion and is then discarded at the next tryCancel(). The signal is the only way to actually abort in-flight foreign work.

The plumbing to consume it already exists end to end:

• SendRequestOptions.signal → send-request.ts:38 → AbortSignal.any merge at base-http-client.ts:121 → fetch(…, { signal }) at :181 → impit.fetch(request, { signal }) in impit-client:105
• HttpCrawler already relies on it for its own navigation: storage.getStore()?.cancelTask.signal — http-crawler.ts:882
• @apify/timeout aborts before it rejects (fire = () => { settled = true; context.cancelTask.abort(); reject(error) }), so the in-flight request rejects, that unwinds the handler, and the already-settled outer promise still reports our TimeoutError

What's missing is only that this is unreachable from supported API. Today it costs an undocumented import and an AsyncLocalStorage poke:

import { storage } from '@apify/timeout';

requestHandler: async ({ sendRequest }) => {
    const signal = storage.getStore()?.cancelTask.signal;
    await sendRequest({ url: '…' }, { signal });
}

We also already ship the other half of this surface publicly — context.extendTimeout(secs) (crawler_commons.ts:253) pushes the deadline, but nothing lets you observe it firing.

Ask

• add context.signal: AbortSignal
• pick its semantics first: context.cancelTask = parent?.cancelTask ?? new AbortController() means non-nested frames own separate controllers, so navigation (http-crawler.ts:462,522,579) and the handler (basic-crawler.ts:2100) have different ones, while raceWithTimeout — the whole-request timeout — has none at all, deliberately (request-timeout.ts:46-48). Inside the handler the answer is unambiguous and useful; elsewhere a naive getter returns a different object per phase, or undefined.

Non-goals

• replacing tryCancel(). It stays the right tool for our own chokepoints (mostly checking on storage access)

[barjin]

Since the rest of the Crawlee API is not AbortSignal-ready, it feels like context.signal would rather stand out. It might be useful for power users calling some long-running operations in the request handler... on the other hand, how often does user code in requestHandler (not the navigation) cause a timeout? 🤔

Perhaps we can start by tunneling the signal to context.sendRequest (maybe that's already happening) and documenting this?

[janbuchar]

Perhaps we can start by tunneling the signal to context.sendRequest (maybe that's already happening) and documenting this?

That's pretty much the point — sendRequest already accepts signal. If we actually add context.signal, sendRequest should probably receive it automatically, so when a request is cancelled from the outside, sendRequest calls will cooperate.

But exposing the signal is also beneficial for users who would like to perform DB calls, for instance, in their request handlers — it will allow them to interrupt orphaned IO safely.