[vdusek]

Adds ActorClient.server(), which returns an ActorServerClient for Server Actors (formerly Actor Standby):

const actorServerClient = client.actor('username/actor-name').server();
const response = await actorServerClient.request('/search', { params: { q: 'apify' } });
const url = await actorServerClient.getUrl();
const spec = await actorServerClient.getOpenApiSpec();

• request() sends a request to the Actor's server. The host always comes from the Actor's standbyUrl. The token goes in the X-Apify-Authorization header, which the platform strips, so headers the caller passes, Authorization included, reach the Actor as they are.
• request() returns the server's response whatever its status. Only 429 and 503 are retried, since other statuses may come from the Actor's code. Network errors and timeouts aren't retried, since the Actor may have already handled the request. It throws only when it gets no response: the Actor doesn't exist or isn't a Server Actor, or the request fails or times out.
• request() sends bodies uncompressed unless compression is set, returns the body parsed, as a buffer, or as a stream depending on responseType, and defaults to the long timeout to cover a cold start.
• getUrl() returns the server URL. It's fetched once per ActorClient, by getUrl() or getOpenApiSpec().
• getOpenApiSpec() returns the web server schema from the build that serves the server (actorStandby.build, or latest), or undefined if there's none.

ActorClient.standby() is a deprecated alias of server() and will be removed in v4.

Other changes:

• ApifyRequestConfig takes new per-request options: compression, authorizationHeader, throwOnErrorStatus, retryStatusCodes, and retryTransportErrors. A custom HTTP client that overrides call() should honor them.
• AxiosHttpClient drops the X-Apify-Authorization header on a redirect to another origin, so an Actor can't redirect the token to another host.
• A Server Actors concepts page, unit tests, and an integration test against a temporary echo Server Actor.

Port of apify/apify-client-python#1153.

Closes: #1159

✍️ Drafted by Claude Code

[github-actions]

⚠️ There are broken links in the documentation.

See more at https://github.com/apify/apify-client-js/actions/runs/41030185240#summary-123977815884

[barjin]

Thank you @vdusek !

I checked mostly the docs and marked some discussion points ⬇️ I also briefly skimmed the CLI RFC, but couldn't find the relevant points for these (I might have missed these, though).

[barjin]

Why don't we do this by default (send the token as X-Apify-Authorization with every standby request)?

Imo we shouldn't limit the set of allowed user-based headers only because some names are used internally.

[vdusek]

ok, so:

• we always use X-Apify-Authorization, platforms authenticates with it, and strips it (it doesnt reach the Actor's code)
• Authorization header is free for the Actor's own auth and is passed through unchanged

[barjin]

first request waits for the platform to start one, which can take a few minutes

...few minutes? I guess we should have kept the "stand-by" naming 😅

[vdusek]

👀 ... dropping all the time-scoped information 😄

[barjin]

I'm not sure I'm sold on this... we don't know anything about the requests / responses of the Actor Server. If it's the standby controller speaking (e.g., rate-limiting the request before it reaches the Actor itself), there it might make sense.

But in case of the Actor Server returning a non-2xx response, I'd rather just return that from the .request() call, not touching it at all.

[vdusek]

Agreed, updated - we now just return the response as is (and only retry 429 and 503)

[barjin]

with the body parsed by its content type in data.

idk how to feel about this. I suppose this means that Content-Type: application/json gets parsed into a JS object?

Is there a way to opt-out of this? Or, e.g., stream the response, or get it as raw bytes etc etc.?

[vdusek]

We could add an option to specify a response type. Check it out now.