feat: make eager activity reservation limit configurable

src/Worker/WorkerOptions.php

@@ -278,6 +278,21 @@ class WorkerOptions
     #[Marshal(name: 'MaxConcurrentEagerActivityExecutionSize')]
     public int $maxConcurrentEagerActivityExecutionSize = 0;
 
+    /**
+     * Optional: Maximum number of activity slots that may be reserved for eager
+     * execution when completing a single workflow task.
+     *
+     * The default of null uses the underlying SDK default of 3. A configured
+     * value must be positive; to disable eager activity execution use
+     * {@see self::$disableEagerActivities} instead.
+     *
+     * @see self::$disableEagerActivities for a description of eager activity execution.
+     *
+     * @since RoadRunner 2025.1.16
+     */
+    #[Marshal(name: 'MaxEagerActivityReservationsPerWorkflowTask')]
+    public ?int $maxEagerActivityReservationsPerWorkflowTask = null;
+
     /**
      * Optional: Disable allowing workflow and activity functions that are
      * registered with custom names from being able to be called with their
@@ -787,6 +802,33 @@ public function withMaxConcurrentEagerActivityExecutionSize(int $size): self
         return $self;
     }
 
+    /**
+     * Optional: Maximum number of activity slots that may be reserved for eager
+     * execution when completing a single workflow task.
+     *
+     * The default of null uses the underlying SDK default of 3. A configured
+     * value must be positive; to disable eager activity execution use
+     * {@see self::withDisableEagerActivities()} instead.
+     *
+     * @see self::$disableEagerActivities for a description of eager activity execution.
+     *
+     * @since RoadRunner 2025.1.16
+     */
+    #[Pure]
+    public function withMaxEagerActivityReservationsPerWorkflowTask(int $value): self
+    {
+        if ($value <= 0) {
+            throw new \InvalidArgumentException(
+                'MaxEagerActivityReservationsPerWorkflowTask must be positive; '
+                . 'use withDisableEagerActivities() to disable eager activity execution.',
+            );
+        }
+
+        $self = clone $this;
+        $self->maxEagerActivityReservationsPerWorkflowTask = $value;
+        return $self;
+    }
+
     /**
      * Optional: Disable allowing workflow and activity functions that are
      * registered with custom names from being able to be called with their

tests/Unit/DTO/WorkerOptionsTestCase.php

@@ -51,6 +51,7 @@ public function testMarshalling(): void
             'MaxHeartbeatThrottleInterval' => null,
             'DisableEagerActivities' => false,
             'MaxConcurrentEagerActivityExecutionSize' => 0,
+            'MaxEagerActivityReservationsPerWorkflowTask' => null,
             'DisableRegistrationAliasing' => false,
             'BuildID' => "",
             'DeploymentOptions' => null,
@@ -334,6 +335,28 @@ public function testMaxConcurrentEagerActivityExecutionSize(): void
         self::assertSame(10, $result->maxConcurrentEagerActivityExecutionSize);
     }
 
+    public function testMaxEagerActivityReservationsPerWorkflowTask(): void
+    {
+        $dto = new WorkerOptions();
+        $result = $dto->withMaxEagerActivityReservationsPerWorkflowTask(10);
+
+        self::assertNotSame($dto, $result);
+        self::assertNull($dto->maxEagerActivityReservationsPerWorkflowTask);
+        self::assertSame(10, $result->maxEagerActivityReservationsPerWorkflowTask);
+        self::assertSame(10, $this->marshal($result)['MaxEagerActivityReservationsPerWorkflowTask']);
+    }
+
+    public function testMaxEagerActivityReservationsPerWorkflowTaskRejectsNonPositive(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage(
+            'MaxEagerActivityReservationsPerWorkflowTask must be positive; '
+            . 'use withDisableEagerActivities() to disable eager activity execution.',
+        );
+
+        (new WorkerOptions())->withMaxEagerActivityReservationsPerWorkflowTask(0);
+    }
+
     public function testDisableRegistrationAliasing(): void
     {
         $dto = new WorkerOptions();