feat: Add inherit timeout option for Actor.call and Actor.start (#518)

- Add `RemainingTime` timeout option for `Actor.call`, `Actor.start` and
`Actor.callTask`. This will set the timeout of another `Actor` run to
whatever is left from the timeout of the current `Actor` run

Related to: apify/apify-client-js#632
Python implementation:
apify/apify-sdk-python#473

---------

Co-authored-by: Jindřich Bär <[email protected]>
Co-authored-by: Jan Buchar <[email protected]>

Author: 3 people

packages/apify/src/actor.ts

@@ -227,18 +227,32 @@ export interface ApifyEnv {
 
 export type UserFunc<T = unknown> = () => Awaitable<T>;
 
-export interface CallOptions extends ActorCallOptions {
+export interface CallOptions extends Omit<ActorCallOptions, 'timeout'> {
     /**
      * User API token that is used to run the Actor. By default, it is taken from the `APIFY_TOKEN` environment variable.
      */
     token?: string;
+    /**
+     * Timeout for the Actor run in seconds, or `'inherit'`.
+     *
+     * Using `inherit` will set timeout of the newly started Actor run to the time
+     * remaining until this Actor run times out so that the new run does not outlive this one.
+     */
+    timeout?: number | 'inherit';
 }
 
-export interface CallTaskOptions extends TaskCallOptions {
+export interface CallTaskOptions extends Omit<TaskCallOptions, 'timeout'> {
     /**
      * User API token that is used to run the Actor. By default, it is taken from the `APIFY_TOKEN` environment variable.
      */
     token?: string;
+    /**
+     * Timeout for the Actor task in seconds, or `'inherit'`.
+     *
+     * Using `inherit` will set timeout of the newly started Actor task to the time
+     * remaining until this Actor run times out so that the new run does not outlive this one.
+     */
+    timeout?: number | 'inherit';
 }
 
 export interface AbortOptions extends RunAbortOptions {
@@ -668,10 +682,13 @@ export class Actor<Data extends Dictionary = Dictionary> {
         input?: unknown,
         options: CallOptions = {},
     ): Promise<ClientActorRun> {
+        const timeout =
+            options.timeout === 'inherit'
+                ? this.getRemainingTime()
+                : options.timeout;
         const { token, ...rest } = options;
         const client = token ? this.newClient({ token }) : this.apifyClient;
-
-        return client.actor(actorId).call(input, rest);
+        return client.actor(actorId).call(input, { ...rest, timeout });
     }
 
     /**
@@ -703,10 +720,14 @@ export class Actor<Data extends Dictionary = Dictionary> {
         input?: unknown,
         options: CallOptions = {},
     ): Promise<ClientActorRun> {
+        const timeout =
+            options.timeout === 'inherit'
+                ? this.getRemainingTime()
+                : options.timeout;
         const { token, ...rest } = options;
         const client = token ? this.newClient({ token }) : this.apifyClient;
 
-        return client.actor(actorId).start(input, rest);
+        return client.actor(actorId).start(input, { ...rest, timeout });
     }
 
     /**
@@ -771,10 +792,14 @@ export class Actor<Data extends Dictionary = Dictionary> {
         input?: Dictionary,
         options: CallTaskOptions = {},
     ): Promise<ClientActorRun> {
+        const timeout =
+            options.timeout === 'inherit'
+                ? this.getRemainingTime()
+                : options.timeout;
         const { token, ...rest } = options;
         const client = token ? this.newClient({ token }) : this.apifyClient;
 
-        return client.task(taskId).call(input, rest);
+        return client.task(taskId).call(input, { ...rest, timeout });
     }
 
     /**
@@ -2325,6 +2350,22 @@ export class Actor<Data extends Dictionary = Dictionary> {
         );
     }
 
+    /**
+     * Get time remaining from the Actor run timeout. Returns `undefined` if not on an Apify platform or the current
+     * run was started without a timeout.
+     */
+    private getRemainingTime(): number | undefined {
+        const env = this.getEnv();
+        if (this.isAtHome() && env.timeoutAt !== null) {
+            return env.timeoutAt.getTime() - Date.now();
+        }
+        log.warning(
+            'Using `inherit` argument is only possible when the Actor is running on the Apify platform and when the ' +
+                'timeout for the Actor run is set.',
+        );
+        return undefined;
+    }
+
     private async inferDefaultsFromInputSchema<T extends Dictionary>(
         input: T,
     ): Promise<T> {

test/apify/actor.test.ts

@@ -891,6 +891,56 @@ describe('Actor', () => {
         });
     });
 
+    describe('inherit timeout option', () => {
+        const { actId, input } = globalOptions;
+        const actorTimeout = 10000;
+        const usedTime = actorTimeout / 2;
+        let testStartTime: Date;
+
+        beforeEach(() => {
+            testStartTime = new Date();
+            process.env[ACTOR_ENV_VARS.TIMEOUT_AT] = new Date(
+                testStartTime.getTime() + actorTimeout,
+            ).toISOString();
+            process.env[APIFY_ENV_VARS.IS_AT_HOME] = '1';
+            vi.setSystemTime(new Date(testStartTime.getTime() + usedTime));
+        });
+
+        afterEach(() => {
+            delete process.env[ACTOR_ENV_VARS.TIMEOUT_AT];
+            delete process.env[APIFY_ENV_VARS.IS_AT_HOME];
+            vitest.restoreAllMocks();
+            vi.useRealTimers();
+        });
+
+        test.each([{ methodName: 'call' }, { methodName: 'start' }])(
+            `Actor.$methodName({timeout: 'inherit'})`,
+            async ({ methodName }) => {
+                const options = { timeout: 'inherit' as const };
+
+                const callSpy = vitest
+                    .spyOn(ActorClient.prototype, methodName)
+                    .mockReturnValue();
+                await Actor[methodName](actId, input, options);
+                expect(callSpy).toBeCalledWith(input, {
+                    timeout: actorTimeout - usedTime,
+                });
+            },
+        );
+
+        test(`Actor.callTask({timeout: 'inherit'})`, async () => {
+            const options = { timeout: 'inherit' as const };
+
+            const callSpy = vitest
+                .spyOn(TaskClient.prototype, 'call')
+                .mockReturnValue();
+            await Actor.callTask(actId, input, options);
+            expect(callSpy).toBeCalledWith(input, {
+                timeout: actorTimeout - usedTime,
+            });
+        });
+    });
+
     // TODO we should remove the duplication if possible
     describe('Actor.call()', () => {
         const { contentType, build, actId, input, token } = globalOptions;