Expose the options that passed the filters

composer.json

@@ -15,7 +15,7 @@
     },
     "require": {
         "php": ">=8.1",
-        "utopia-php/telemetry": "0.1.*"
+        "utopia-php/telemetry": "^0.4.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^9.3",

src/Balancer/Balancer.php

@@ -46,15 +46,29 @@ public function addFilter(callable $filter): self
         return $this;
     }
 
-    public function run(): ?Option
+    /**
+     * Every option that passed all filters, in the order they were added.
+     *
+     * `run()` narrows this to one option through the algorithm. Callers that
+     * have to act on all of them — fanning a request out to every option that
+     * qualifies, rather than balancing between them — read them here.
+     *
+     * @return Option[]
+     */
+    public function getFilteredOptions(): array
     {
         $options = $this->options;
 
         foreach ($this->filters as $filter) {
             $options = \array_filter($options, $filter);
         }
 
-        $options = \array_values($options);
+        return \array_values($options);
+    }
+
+    public function run(): ?Option
+    {
+        $options = $this->getFilteredOptions();
 
         if (\count($options) === 0) {
             return null;

tests/Balancer/BalancerTest.php

@@ -244,4 +244,40 @@ public function testGetOptions(): void
         $this->assertEquals('fra-2', $groupOptions[4]->getState('dataCenter'));
         $this->assertEquals('lon-1', $groupOptions[5]->getState('dataCenter'));
     }
+
+    public function testFilteredOptions(): void
+    {
+        $balancer = new Balancer(new First());
+
+        $balancer
+            ->addOption(new Option(['hostname' => 'worker-1', 'isOnline' => true, 'cpu' => 80]))
+            ->addOption(new Option(['hostname' => 'worker-2', 'isOnline' => false, 'cpu' => 20]))
+            ->addOption(new Option(['hostname' => 'worker-3', 'isOnline' => true, 'cpu' => 35]));
+
+        // Unfiltered, every option qualifies
+        $this->assertCount(3, $balancer->getFilteredOptions());
+
+        $balancer->addFilter(fn ($option) => $option->getState('isOnline') === true);
+
+        $filtered = $balancer->getFilteredOptions();
+
+        // All survivors, not just the one the algorithm would pick
+        $this->assertCount(2, $filtered);
+        $this->assertEquals('worker-1', $filtered[0]->getState('hostname'));
+        $this->assertEquals('worker-3', $filtered[1]->getState('hostname'));
+        $this->assertEquals('worker-1', ($balancer->run() ?? new Option([]))->getState('hostname'));
+
+        $balancer->addFilter(fn ($option) => $option->getState('cpu') < 50);
+
+        $filtered = $balancer->getFilteredOptions();
+
+        // Filters compose, and the keys are reindexed from zero
+        $this->assertCount(1, $filtered);
+        $this->assertEquals('worker-3', $filtered[0]->getState('hostname'));
+
+        $balancer->addFilter(fn ($option) => false);
+
+        $this->assertSame([], $balancer->getFilteredOptions());
+        $this->assertNull($balancer->run());
+    }
 }