Add Locality API (getBoundaryKeys)

src/Locality.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CrazyGoat\FoundationDB;
+
+final class Locality
+{
+    private const KEY_SERVERS_PREFIX = "\xFF/keyServers/";
+
+    /**
+     * @return list<string>
+     */
+    public static function getBoundaryKeys(Database $db, string $begin, string $end): array
+    {
+        $boundaries = [];
+        $currentBegin = $begin;
+
+        while ($currentBegin < $end) {
+            $tr = $db->createTransaction();
+            $tr->options()->setReadSystemKeys();
+            $tr->options()->setLockAware();
+
+            $lastBegin = $currentBegin;
+
+            try {
+                $rangeResult = $tr->snapshot()->getRange(
+                    self::KEY_SERVERS_PREFIX . $currentBegin,
+                    self::KEY_SERVERS_PREFIX . $end,
+                );
+
+                foreach ($rangeResult as $kv) {
+                    $key = substr($kv->key, strlen(self::KEY_SERVERS_PREFIX));
+                    $boundaries[] = $key;
+                    $currentBegin = $key . "\x00";
+                }
+
+                $currentBegin = $end;
+            } catch (FDBException $e) {
+                if ($e->fdbCode === 1007 && $currentBegin !== $lastBegin) {
+                    continue;
+                }
+
+                $tr->onError($e->fdbCode)->await();
+            }
+        }
+
+        return $boundaries;
+    }
+}

tests/Integration/LocalityTest.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CrazyGoat\FoundationDB\Tests\Integration;
+
+use CrazyGoat\FoundationDB\Database;
+use CrazyGoat\FoundationDB\FoundationDB;
+use CrazyGoat\FoundationDB\Locality;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class LocalityTest extends TestCase
+{
+    private static bool $initialized = false;
+
+    private static Database $db;
+
+    protected function setUp(): void
+    {
+        if (!self::$initialized) {
+            FoundationDB::reset();
+            FoundationDB::apiVersion(730);
+            self::$db = FoundationDB::open();
+            self::$initialized = true;
+        }
+    }
+
+    #[Test]
+    public function getBoundaryKeysReturnsNonEmptyArray(): void
+    {
+        self::$db->set('test/locality/a', 'value');
+
+        $boundaries = Locality::getBoundaryKeys(self::$db, '', "\xFF");
+
+        self::assertNotEmpty($boundaries);
+    }
+
+    #[Test]
+    public function getBoundaryKeysContainsOnlyStrings(): void
+    {
+        $boundaries = Locality::getBoundaryKeys(self::$db, '', "\xFF");
+
+        self::assertNotEmpty($boundaries);
+        self::assertContainsOnly('string', $boundaries);
+    }
+
+    #[Test]
+    public function getBoundaryKeysWithNarrowRange(): void
+    {
+        for ($i = 0; $i < 5; $i++) {
+            self::$db->set("test/locality/narrow/{$i}", str_repeat('x', 100));
+        }
+
+        $boundaries = Locality::getBoundaryKeys(self::$db, 'test/locality/narrow/', 'test/locality/narrow0');
+
+        self::assertGreaterThanOrEqual(0, count($boundaries));
+    }
+
+    #[Test]
+    public function getBoundaryKeysWithEmptyRangeReturnsEmptyArray(): void
+    {
+        $boundaries = Locality::getBoundaryKeys(self::$db, "\xFE", "\xFE");
+
+        self::assertSame([], $boundaries);
+    }
+
+    #[Test]
+    public function getBoundaryKeysAreSorted(): void
+    {
+        $boundaries = Locality::getBoundaryKeys(self::$db, '', "\xFF");
+
+        self::assertGreaterThanOrEqual(1, count($boundaries));
+
+        $count = count($boundaries);
+
+        for ($i = 1; $i < $count; $i++) {
+            self::assertGreaterThan(
+                $boundaries[$i - 1],
+                $boundaries[$i],
+                'Boundary keys should be in ascending order',
+            );
+        }
+    }
+}