Skip to content

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

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

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

Conversation

@vdusek

@vdusek vdusek commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Adds ActorClient.server_request() (and the async twin) for sending HTTP requests to a Server Actor, so users don't have to look up the server URL and attach the token by hand.

response = client.actor('username/actor-name').server_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 platform 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 server URL is fetched on the first call and reused by the same client.
  • Request bodies are sent uncompressed by default, since Actor 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 server 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 server_request.

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

Naming follows the Server Actors rename. The API still calls the feature Standby (standbyUrl, actorStandby), so the model field stays standby_url. Includes a concepts page covering authentication, compression, timeouts, and retries.

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 (9488677) to head (5f04b11).

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #1153      +/-   ##
==========================================
+ Coverage   95.53%   95.56%   +0.03%     
==========================================
  Files          61       61              
  Lines        5976     5997      +21     
==========================================
+ Hits         5709     5731      +22     
+ Misses        267      266       -1     
Flag Coverage Δ
integration 90.41% <41.66%> (-0.37%) ⬇️
unit 89.84% <100.00%> (+0.05%) ⬆️

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
@vdusek vdusek changed the title feat: add standby_request for calling Standby Actors, with per-request compression in HTTP clients feat: add server_request for calling Server Actors, with per-request compression in HTTP clients Oct 23, 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