Refactor Run scheduling

[gullmar]

This PR extracts and isolates the logic to schedule Actor Runs, which was previously split between ExtApifyClient, ExtActorClient, ExtTaskClient, and Queue. In doing so, the duplication between ExtActorClient and ExtTaskClient was greatly reduced.

A few abstractions were introduced to deal with scheduling:

• DeferredPromise is a promise that can be instantiated and then waited by multiple observers and solved, in any order.
• TrySync is a synchronization primitive that allows deciding if a function should be executed in a given moment or not. In practice, this is used to control whether we should attempt starting a Run or not. There are three implementations of such sync primitives:
  • A lock is used to prevent starting multiple Runs at the same time, preventing hitting the rate limit by design. In the future, we could replace the lock with a semaphore or another more sophisticated mechanism, to allow starting multiple Runs faster.
  • A "cooldown manager" is used to ensure that we wait some time if we incur in some known error, namely not enough memory or not enough jobs available. The back-off logic is very trivial, just a fixed cooldown is applied every time, which is fine in our case, but could be tuned better if we decide to challenge the rate limit more closely, for example.
  • A gate is used to avoid any Run start when the Actor is shutting down.
• Request and RequestPool are generic classes used to manage Run start requests.
• RunSource is an entity that can start a Run. In practice, an ActorClient or a TaskClient.
• Outcome is a TypeScript object representing a named state together with a value. It's used to enforce type safety and full coverage when we process a value that may represent two or more variants. There are some examples in the code.

The scheduling logic is mainly in the RunScheduler component.

The context, which was previously an interface, has now been split into two classes: OrchestratoContext and ClientContext. They hold data which is relevant at the orchestrator and the Apify client level, respectively, together with convenient methods.

The unit tests were updated to cover all the changed parts.

Here is an end-to-end successful test: https://console.apify.com/view/runs/0afqmU3n80Fk6drMq

[Copilot]

Pull request overview

This PR refactors the run scheduling architecture by extracting scheduling logic from client classes into dedicated utilities, significantly improving code organization and reducing duplication.

Key Changes:

• Introduced new scheduling utilities (RequestPool, MessageQueue, RunScheduler, Cooldown, RunLongInterval) to handle asynchronous run management
• Removed the enqueue and enqueueBatch methods from Actor and Task clients
• Updated type definitions from object to Dictionary for input parameters throughout the codebase

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 19 comments.

Show a summary per file

File	Description
src/utils/scheduling/pool.ts	New request pool managing pending/in-progress run requests with result caching
src/utils/scheduling/message-queue.ts	New message queue for async waiter notification pattern
src/utils/scheduling/message.ts	New Result-like wrapper for success/error handling
src/utils/scheduling/interval.ts	New run-long interval utility with lifecycle management
src/utils/scheduling/cooldown.ts	New cooldown mechanism for rate limiting retry attempts
src/run-scheduler.ts	New centralized scheduler coordinating run requests with retry logic
src/clients/apify-client.ts	Refactored to delegate scheduling to RunScheduler, simplified from ~200 to ~100 lines
src/clients/actor-client.ts	Simplified by removing scheduling logic, delegates to apifyClient.startRun
src/clients/task-client.ts	Similar simplification to actor-client, removed duplicated code
src/clients/run-client.ts	Updated to use new context types, replaced superClient with super calls
src/clients/dataset-client.ts	Minor cleanup replacing superClient references with super calls
src/run-tracker.ts	Updated context types, changed getCurrentRunNames to return full run info
src/types.ts	Removed deprecated types, updated input types to Dictionary
src/utils/*.ts	Updated type signatures from object to Dictionary
src/constants.ts	Removed unused RUN_STATUSES constant
CHANGELOG.md	Documents breaking changes for removed methods and type updates

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 15 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.