HttpClient has three abstract entry points (crawl, send_request, stream in http_clients/_base.py). Each implementation re-implements redirect hops, the per-hop Cookie header, stripping credentials on cross-origin redirects and saving Set-Cookie into the session: ImpitHttpClient._request_with_redirects, the HttpxHttpClient transport adapter, and the curl client. A custom client has to get all of that right on its own.

JS v4 moved cookie and redirect handling into a BaseHttpClient, and a custom client implements a single fetch-like method. This is the concrete shape for #874.

Proposed solution

• An abstract per-hop primitive that a client implements. The base class follows redirects, assembles cookies from the session and persists response cookies, once for all clients.
• Merge a Cookie header passed by the caller with the session cookies by name, with the caller winning per cookie. Today the caller's header replaces the session cookies entirely, in both impit and httpx. Consider a per-call cookie jar override, as in JS.
• Rename persist_cookies_per_session to save_response_cookies, and decide whether it becomes a crawler option, as in JS.

This will be a breaking change.

JS references

• fetch API and BaseHttpClient: feat: fetch API for custom http clients crawlee#3326 (closes Make the HttpClient interface more compatible with fetch crawlee#3071, Extract GotScrapingHttpClient to a separate package and replace with FetchHttpClient crawlee#3314)
• Cookie handling: Crawling context sendRequest cookies can't be easily overriden crawlee#2744, Refactor cookie handling crawlee#3271
• saveResponseCookies: feat: rename persistCookiesPerSession to saveResponseCookies, various fixes crawlee#3606
• Redirect fixes on the base class: fix(http-client): replay the request body on redirects without throwing crawlee#4136, fix(http-client): do not forward credentials across cross-origin redirects crawlee#4137, fix(http-client): do not reuse cookies of the previous hop on same-origin redirects crawlee#4154

✍️ Drafted by Claude Code