fix(snowflake): Reject time before epoch

This allow to simplify a bit the code, also add a small description of
the algorithm.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Carl Schwan <carl@carlschwan.eu>

Author: CarlSchwan

lib/private/Snowflake/FileSequence.php

@@ -13,6 +13,19 @@
 use OCP\ITempManager;
 use Override;
 
+/**
+ * Sequence IDs shared between processes through lock files in the temporary directory.
+ *
+ * Each lock file is a table of counters. To get a sequence ID, the file chosen by the
+ * millisecond (ms % NB_FILES) is locked and the slot of that second and millisecond is
+ * read: ((seconds % SEQUENCE_TTL) * (1000 / NB_FILES) + ms / NB_FILES). A slot holds the
+ * seconds it was last used for and the last sequence ID handed out. If the seconds match,
+ * the next sequence ID is that one plus one, otherwise it starts at 0. The result is
+ * written back and the file unlocked.
+ *
+ * A slot is reused SEQUENCE_TTL seconds later, the seconds mismatch then resets its counter.
+ * No fsync is needed, as the files only coordinate processes running at the same time.
+ */
 class FileSequence implements ISequence {
 	/** Number of files to use */
 	private const NB_FILES = 20;
@@ -72,22 +85,20 @@ public function nextId(int $serverId, int $seconds, int $milliseconds): int {
 		}
 
 		// Each file holds one slot per second of the TTL window and per millisecond mapped to it
-		$slot = (($seconds % self::SEQUENCE_TTL + self::SEQUENCE_TTL) % self::SEQUENCE_TTL) * intdiv(1000, self::NB_FILES)
-			+ intdiv($milliseconds, self::NB_FILES);
-		$slotSecondsKey = $seconds & 0xFFFFFFFF;
+		$slot = ($seconds % self::SEQUENCE_TTL) * intdiv(1000, self::NB_FILES) + intdiv($milliseconds, self::NB_FILES);
 		fseek($fp, $slot * self::SLOT_SIZE);
 		$data = fread($fp, self::SLOT_SIZE);
 		$sequenceId = 0;
 		if (is_string($data) && strlen($data) === self::SLOT_SIZE) {
 			['seconds' => $slotSeconds, 'sequence' => $slotSequenceId] = unpack('Nseconds/Nsequence', $data);
-			if ($slotSeconds === $slotSecondsKey) {
+			if ($slotSeconds === $seconds) {
 				$sequenceId = $slotSequenceId + 1;
 			}
 		}
 
 		// No fsync needed, the file only coordinates processes running at the same time
 		fseek($fp, $slot * self::SLOT_SIZE);
-		fwrite($fp, pack('NN', $slotSecondsKey, $sequenceId));
+		fwrite($fp, pack('NN', $seconds, $sequenceId));
 
 		// Release lock
 		fclose($fp);

lib/private/Snowflake/ISequence.php

@@ -20,6 +20,8 @@ public function isAvailable(): bool;
 
 	/**
 	 * Returns next sequence ID for current time and server
+	 *
+	 * @param non-negative-int $seconds seconds since the Snowflake epoch
 	 */
 	public function nextId(int $serverId, int $seconds, int $milliseconds): int|false;
 }

lib/private/Snowflake/SnowflakeGenerator.php

@@ -33,6 +33,9 @@ public function __construct(
 	public function nextId(): string {
 		// Relative time
 		[$seconds, $milliseconds] = $this->getCurrentTime();
+		if ($seconds < 0) {
+			throw new \InvalidArgumentException('Snowflake IDs cannot be generated for a time before ' . date(DATE_ATOM, self::TS_OFFSET));
+		}
 
 		$serverId = $this->getServerId(); // Already 9 bits
 		$isCli = (int)$this->isCli(); // 1 bit

lib/public/Snowflake/ISnowflakeGenerator.php

@@ -39,6 +39,7 @@ interface ISnowflakeGenerator {
 	 *
 	 * Each call to this method is guaranteed to return a different ID.
 	 *
+	 * @throws \InvalidArgumentException if the current time is before 2025-10-01, as such a time cannot be represented
 	 * @since 33.0
 	 */
 	public function nextId(): string;

tests/lib/Snowflake/FileSequenceTest.php

@@ -12,13 +12,11 @@
 use OC\Snowflake\FileSequence;
 use OCP\ITempManager;
 
-/**
- * @package Test
- */
 class FileSequenceTest extends ISequenceBase {
 	private string $path;
 
 	public function setUp():void {
+		parent::setUp();
 		$tempManager = $this->createMock(ITempManager::class);
 		$this->path = sys_get_temp_dir() . '/' . uniqid('file_sequence_test_');
 		mkdir($this->path);
@@ -34,6 +32,7 @@ public function tearDown():void {
 			rmdir($directory);
 		}
 		rmdir($this->path);
+		parent::tearDown();
 	}
 
 	public function testSequenceIncrementsWithinTheSameMillisecond(): void {
@@ -56,10 +55,4 @@ public function testSequenceKeepsEarlierMillisecondsWithinTheWindow(): void {
 		$this->assertSame(0, $this->sequence->nextId(42, 1001, 500));
 		$this->assertSame(1, $this->sequence->nextId(42, 1000, 500));
 	}
-
-	public function testSequenceWithSecondsBeforeTheEpoch(): void {
-		$this->assertSame(0, $this->sequence->nextId(42, -5, 10));
-		$this->assertSame(1, $this->sequence->nextId(42, -5, 10));
-		$this->assertSame(0, $this->sequence->nextId(42, 25, 10));
-	}
 }

tests/lib/Snowflake/GeneratorTest.php

@@ -63,6 +63,15 @@ public function testGenerator(): void {
 		$this->assertEquals(42, $data->getServerId());
 	}
 
+	public function testGeneratorRejectsTimeBeforeEpoch(): void {
+		$timeFactory = $this->createMock(ITimeFactory::class);
+		$timeFactory->method('now')->willReturn(new \DateTimeImmutable('2025-09-30 23:59:59 UTC'));
+		$generator = new SnowflakeGenerator($timeFactory, $this->config, $this->sequence);
+
+		$this->expectException(\InvalidArgumentException::class);
+		$generator->nextId();
+	}
+
 	#[DataProvider('provideSnowflakeData')]
 	public function testGeneratorWithFixedTime(string $date, int $expectedSeconds, int $expectedMilliseconds): void {
 		$dt = new \DateTimeImmutable($date);