fix: Warn when a requested timeout is capped at timeout_max

[vdusek]

An explicit per-call timeout timedelta larger than timeout_max (default 360 s), or a tier configured above it, is clamped to timeout_max on every attempt. For example, dataset.get_items_as_bytes(timeout=timedelta(minutes=30)) runs every attempt with a 360 s timeout and surfaces as repeated impit.TimeoutException, with no hint that the requested 30 minutes never took effect.

The behavior stays unchanged: timeout_max remains a hard ceiling for any single request attempt. Only visibility changes. _compute_timeout now logs a warning when the resolved base timeout exceeds timeout_max, naming both values and pointing at timeout_max as the knob to raise.

The warning goes through LoggerOnce, a small dedup helper ported from Crawlee for Python, so a recurring cut-off is reported once per timeout kind rather than on every attempt of every call.

Docs and docstrings now state that the cap applies to tier and per-call timeouts alike.

✍️ Drafted by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.86%. Comparing base (c1bffc6) to head (99b5174).
⚠️ Report is 44 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #962      +/-   ##
==========================================
+ Coverage   94.64%   94.86%   +0.22%     
==========================================
  Files          58       58              
  Lines        5263     5357      +94     
==========================================
+ Hits         4981     5082     +101     
+ Misses        282      275       -7     

Flag	Coverage Δ
integration	92.25% <75.00%> (-0.06%)	⬇️
unit	84.63% <100.00%> (+0.69%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Pijukatel]

Can you please verify in the API code that a timeout larger than 360 s has any meaning?

If there is some hard-coded or implementation limit on the API side, it makes no sense to lift the limit in the client.

(But a warning might be good in those cases)

[vdusek]

Probably, there are mostly idle timeouts, not wall-clock timeouts, so this could make sense. See:

Verified in apify-core — yes, it has meaning. The 360 s on the server side is an idle timeout, while impit's timeout is a total wall-clock budget, so the client cap was stricter than anything the API enforces.

• The only 360 s on the path is the ALB idle timeout on the api.* ingress (deploy/helm/helmfile.yaml:306); api.apify.com goes straight to that ALB. It fires only when no bytes flow for 360 s.
• No wall-clock cap on responses: no requestTimeout/keepAliveTimeout override (src/api/src/lib/api_server.ts:208), no timeout middleware, and respondWithDatasetItemsStream (lib/datasets.ts:541) streams with no deadline. The API even writes a space every second to keep the socket busy (lib/actor_jobs.ts:147, routes/datasets/items.ts:147) — it's built for requests outliving the idle timeout.
• Verified impit's semantics: a 6 s stream that's never idle >1 s still fails at exactly 3.0 s under timeout=3. So a 10-minute export is legal server-side but the old min() aborted it at 360 s — the reported failure.
• Server-side caps that do exist are all below 360 s and return a proper response: MAX_ACTOR_JOB_SYNC_WAIT_SECS = 300 / ASYNC = 60. Node's default requestTimeout = 300 s does hard-cap uploads (408), but that's a case for raising it on the API side, not for silently shrinking an explicit user value.

I don't want to waste much time here. IMO, silently truncating it is definitely wrong. If we don't want to allow longer timeouts, we should at least log a warning. However, allowing longer timeouts wouldn't be harmful anyway. I'll wait for your response, but I don't have a strong preference here.