Skip to content

feat: add standby_request for calling Standby Actors, with per-request compression in HTTP clients - #1153

Draft
vdusek wants to merge 9 commits into
masterfrom
feat/standby-request
Draft

vdusek wants to merge 9 commits into
masterfrom
feat/standby-request

Conversation

@vdusek

@vdusek vdusek commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Adds ActorClient.standby_request() (and the async twin) for sending HTTP requests to an Actor in Standby mode, so users don't have to look up standby_url and attach the token by hand.

response = client.actor('username/actor-name').standby_request('/search', params={'q': 'apify'})

The design follows the CLI RFC (apify/apify-cli#1299):

  • The caller passes a path, never a URL. The host always comes from the Actor's standbyUrl returned by the API, so the token can't be sent to another host. Both built-in HTTP clients drop Authorization on a cross-host redirect.
  • The token goes in the Authorization header. The Standby router removes it before forwarding, so it never reaches the Actor's code. An Actor that reads Authorization for its own auth gets the Apify token in X-Apify-Authorization instead, as described in the platform docs.
  • The standbyUrl is fetched on the first call and reused by the same client.
  • Request bodies are sent uncompressed by default, since Standby servers may not decode them. The compression argument opts in, with an algorithm name or an HttpCompressor.
  • The timeout defaults to long, since the first request to an idle Actor waits for a Standby run to start.
  • Error statuses raise ApifyApiError, and 5xx/429 are retried like API calls. The docs say so, because a non-idempotent endpoint may get the request twice.

To support the opt-in, HttpClient.call and HttpClientAsync.call take a per-request compression argument: True uses the client's compressor, an HttpCompressor is used for that request only, and False sends the body uncompressed. A custom HTTP client that replaces call itself (not just send_request) needs to accept the new argument to work with standby_request.

Also fixes the async docstring sync script, which turned ApifyClientError into the nonexistent ApifyClientAsyncError.

Naming keeps standby, as agreed in #product-server-actors until the Server Actors rename reaches the API. Includes a concepts page covering authentication, compression, timeouts, and retries. JS parity: apify/apify-client-js#1159.

Open question: keep standby (it matches the current API fields standbyUrl and actorStandby), switch to "server" to follow the Server Actors rename, or keep standby and mark the method experimental so it can be renamed later?

Closes: #973

✍️ Drafted by Claude Code

@vdusek vdusek added the t-tooling Issues with this label are in the ownership of the tooling team. label Oct 19, 2026
@vdusek vdusek self-assigned this Oct 19, 2026
@codecov

codecov Bot commented Oct 19, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.56%. Comparing base (304c8e9) to head (b3995a6).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #1153      +/-   ##
==========================================
+ Coverage   95.53%   95.56%   +0.03%     
==========================================
  Files          61       61              
  Lines        5974     5995      +21     
==========================================
+ Hits         5707     5729      +22     
+ Misses        267      266       -1     
Flag Coverage Δ
integration 90.82% <41.66%> (+0.19%) ⬆️
unit 89.84% <100.00%> (+0.82%) ⬆️

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.

vdusek added a commit to apify/apify-docs that referenced this pull request Oct 20, 2026
While working on better support for calling Standby Actors from the API
client (apify/apify-client-python#1153), I couldn't find an explanation
of how the authentication headers are handled (Maybe I just missed it?).
I have two questions:

1. Does the Apify token reach the Actor's code? (It shouldn't.).
2. If an Actor needs its own authentication header, what's the best
practice for sending it? Is it `X-Apify-Authorization`?

I drafted a change; see the diff and suggest better/correct/more precise
explanation. Thank you.

(tagging @mvolfik, as I know a lot of the work there was done by you)
@vdusek
vdusek requested review from Pijukatel and removed request for Pijukatel October 20, 2026 06:58
@vdusek vdusek changed the title feat: add standby_request for calling Standby Actors feat: add standby_request for calling Standby Actors, with per-request compression in HTTP clients Oct 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

t-tooling Issues with this label are in the ownership of the tooling team.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for standby Actors

2 participants