(refactor): share schedule spread offset

This commit is contained in:
Jake Barnby committed 2026-08-10 23:09:17 +12:00
1 parent 5db0e991e3
commit d45162c12a
4 files changed
+73 -63

No files matched your search

@@ -36,6 +36,18 @@ abstract class ScheduleBase extends Action
abstract public static function getSupportedResource(): string;
abstract public static function getCollectionId(): string;
/**
* Deterministic per-resource offset, in seconds, within [0, $window).
*
* Schedules that share a cron slot are spread across the window instead
* of all being enqueued in the same second, while each resource keeps a
* stable slot so run intervals stay exact.
*/
public static function spreadOffset(string $resourceId, int $window): int
{
return $window <= 1 ? 0 : \abs(\crc32($resourceId)) % $window;
}
protected function loadResource(Document $project, callable $getProjectDB, array $schedule): Document
{
return $getProjectDB($project)->getDocument(static::getCollectionId(), $schedule['resourceId']);
@@ -37,18 +37,6 @@ class ScheduleFunctions extends ScheduleBase
return RESOURCE_TYPE_FUNCTIONS;
}
/**
* Deterministic per-function offset, in seconds, within [0, $window).
*
* Schedules that share a cron slot (everyone runs `0 * * * *`) are spread
* across the window instead of all being enqueued in the same second,
* while each function keeps a stable slot so run intervals stay exact.
*/
public static function spreadOffset(string $resourceId, int $window): int
{
return $window <= 1 ? 0 : \abs(\crc32($resourceId)) % $window;
}
/**
* Spread window, in seconds, for a given schedule. The default applies
* _APP_FUNCTIONS_SCHEDULE_SPREAD to every schedule; override to scope
@@ -0,0 +1,61 @@
<?php
declare(strict_types=1);
namespace Tests\Unit\Platform\Tasks;
use Appwrite\Platform\Tasks\ScheduleBase;
use PHPUnit\Framework\TestCase;
final class ScheduleBaseTest extends TestCase
{
public function testSpreadOffsetIsDeterministic(): void
{
$this->assertSame(
ScheduleBase::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', 60),
ScheduleBase::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', 60)
);
}
public function testSpreadOffsetIsBounded(): void
{
foreach ($this->sampleIds() as $id) {
foreach ([2, 30, 60, 300] as $window) {
$offset = ScheduleBase::spreadOffset($id, $window);
$this->assertGreaterThanOrEqual(0, $offset);
$this->assertLessThan($window, $offset);
}
}
}
public function testSpreadOffsetIsZeroWhenDisabled(): void
{
$this->assertSame(0, ScheduleBase::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', 1));
$this->assertSame(0, ScheduleBase::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', 0));
$this->assertSame(0, ScheduleBase::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', -5));
}
public function testSpreadOffsetDispersesDistinctResources(): void
{
$offsets = [];
foreach ($this->sampleIds() as $id) {
$offsets[] = ScheduleBase::spreadOffset($id, 60);
}
// Resources sharing a cron slot must not all land in the same second.
$this->assertGreaterThan(10, count(array_unique($offsets)));
}
/**
* @return string[]
*/
private function sampleIds(): array
{
$ids = [];
for ($i = 0; $i < 50; $i++) {
$ids[] = md5("resource-{$i}");
}
return $ids;
}
}
@@ -13,44 +13,6 @@ use Utopia\Database\Database;
final class ScheduleFunctionsTest extends TestCase
{
public function testSpreadOffsetIsDeterministic(): void
{
$this->assertSame(
ScheduleFunctions::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', 60),
ScheduleFunctions::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', 60)
);
}
public function testSpreadOffsetIsBounded(): void
{
foreach ($this->sampleIds() as $id) {
foreach ([2, 30, 60, 300] as $window) {
$offset = ScheduleFunctions::spreadOffset($id, $window);
$this->assertGreaterThanOrEqual(0, $offset);
$this->assertLessThan($window, $offset);
}
}
}
public function testSpreadOffsetIsZeroWhenDisabled(): void
{
$this->assertSame(0, ScheduleFunctions::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', 1));
$this->assertSame(0, ScheduleFunctions::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', 0));
$this->assertSame(0, ScheduleFunctions::spreadOffset('64f5c8e2a1b3d4e5f6a7b8c9', -5));
}
public function testSpreadOffsetDispersesDistinctFunctions(): void
{
$offsets = [];
foreach ($this->sampleIds() as $id) {
$offsets[] = ScheduleFunctions::spreadOffset($id, 60);
}
// The whole point: functions sharing a cron slot must not all land
// in the same second. Expect real dispersion across the window.
$this->assertGreaterThan(10, count(array_unique($offsets)));
}
public function testSpreadWindowDefaultsToEnv(): void
{
$task = new class () extends ScheduleFunctions {
@@ -74,17 +36,4 @@ final class ScheduleFunctionsTest extends TestCase
: putenv("_APP_FUNCTIONS_SCHEDULE_SPREAD={$previous}");
}
}
/**
* @return string[]
*/
private function sampleIds(): array
{
$ids = [];
for ($i = 0; $i < 50; $i++) {
$ids[] = md5("function-{$i}");
}
return $ids;
}
}