feat(database): introduce Snowflake IDs generator

Signed-off-by: Benjamin Gaussorgues <[email protected]>

Author: Altahrim

lib/composer/composer/autoload_classmap.php

@@ -628,6 +628,8 @@
     'OCP\\IRequestId' => $baseDir . '/lib/public/IRequestId.php',
     'OCP\\IServerContainer' => $baseDir . '/lib/public/IServerContainer.php',
     'OCP\\ISession' => $baseDir . '/lib/public/ISession.php',
+    'OCP\\ISnowflakeId' => $baseDir . '/lib/public/ISnowflakeId.php',
+    'OCP\\ISnowflakeIdGenerator' => $baseDir . '/lib/public/ISnowflakeIdGenerator.php',
     'OCP\\IStreamImage' => $baseDir . '/lib/public/IStreamImage.php',
     'OCP\\ITagManager' => $baseDir . '/lib/public/ITagManager.php',
     'OCP\\ITags' => $baseDir . '/lib/public/ITags.php',
@@ -1871,6 +1873,7 @@
     'OC\\OCS\\CoreCapabilities' => $baseDir . '/lib/private/OCS/CoreCapabilities.php',
     'OC\\OCS\\DiscoveryService' => $baseDir . '/lib/private/OCS/DiscoveryService.php',
     'OC\\OCS\\Provider' => $baseDir . '/lib/private/OCS/Provider.php',
+    'OC\\OpenMetrics\\Exporters\\RunningJobs' => $baseDir . '/lib/private/OpenMetrics/Exporters/RunningJobs.php',
     'OC\\PhoneNumberUtil' => $baseDir . '/lib/private/PhoneNumberUtil.php',
     'OC\\PreviewManager' => $baseDir . '/lib/private/PreviewManager.php',
     'OC\\PreviewNotAvailableException' => $baseDir . '/lib/private/PreviewNotAvailableException.php',
@@ -2103,6 +2106,8 @@
     'OC\\Share\\Constants' => $baseDir . '/lib/private/Share/Constants.php',
     'OC\\Share\\Helper' => $baseDir . '/lib/private/Share/Helper.php',
     'OC\\Share\\Share' => $baseDir . '/lib/private/Share/Share.php',
+    'OC\\SnowflakeId' => $baseDir . '/lib/private/SnowflakeId.php',
+    'OC\\SnowflakeIdGenerator' => $baseDir . '/lib/private/SnowflakeIdGenerator.php',
     'OC\\SpeechToText\\SpeechToTextManager' => $baseDir . '/lib/private/SpeechToText/SpeechToTextManager.php',
     'OC\\SpeechToText\\TranscriptionJob' => $baseDir . '/lib/private/SpeechToText/TranscriptionJob.php',
     'OC\\StreamImage' => $baseDir . '/lib/private/StreamImage.php',

lib/composer/composer/autoload_static.php

@@ -11,32 +11,32 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
     );
 
     public static $prefixLengthsPsr4 = array (
-        'O' =>
+        'O' => 
         array (
             'OC\\Core\\' => 8,
             'OC\\' => 3,
             'OCP\\' => 4,
         ),
-        'N' =>
+        'N' => 
         array (
             'NCU\\' => 4,
         ),
     );
 
     public static $prefixDirsPsr4 = array (
-        'OC\\Core\\' =>
+        'OC\\Core\\' => 
         array (
             0 => __DIR__ . '/../../..' . '/core',
         ),
-        'OC\\' =>
+        'OC\\' => 
         array (
             0 => __DIR__ . '/../../..' . '/lib/private',
         ),
-        'OCP\\' =>
+        'OCP\\' => 
         array (
             0 => __DIR__ . '/../../..' . '/lib/public',
         ),
-        'NCU\\' =>
+        'NCU\\' => 
         array (
             0 => __DIR__ . '/../../..' . '/lib/unstable',
         ),
@@ -669,6 +669,8 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\IRequestId' => __DIR__ . '/../../..' . '/lib/public/IRequestId.php',
         'OCP\\IServerContainer' => __DIR__ . '/../../..' . '/lib/public/IServerContainer.php',
         'OCP\\ISession' => __DIR__ . '/../../..' . '/lib/public/ISession.php',
+        'OCP\\ISnowflakeId' => __DIR__ . '/../../..' . '/lib/public/ISnowflakeId.php',
+        'OCP\\ISnowflakeIdGenerator' => __DIR__ . '/../../..' . '/lib/public/ISnowflakeIdGenerator.php',
         'OCP\\IStreamImage' => __DIR__ . '/../../..' . '/lib/public/IStreamImage.php',
         'OCP\\ITagManager' => __DIR__ . '/../../..' . '/lib/public/ITagManager.php',
         'OCP\\ITags' => __DIR__ . '/../../..' . '/lib/public/ITags.php',
@@ -1912,6 +1914,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\OCS\\CoreCapabilities' => __DIR__ . '/../../..' . '/lib/private/OCS/CoreCapabilities.php',
         'OC\\OCS\\DiscoveryService' => __DIR__ . '/../../..' . '/lib/private/OCS/DiscoveryService.php',
         'OC\\OCS\\Provider' => __DIR__ . '/../../..' . '/lib/private/OCS/Provider.php',
+        'OC\\OpenMetrics\\Exporters\\RunningJobs' => __DIR__ . '/../../..' . '/lib/private/OpenMetrics/Exporters/RunningJobs.php',
         'OC\\PhoneNumberUtil' => __DIR__ . '/../../..' . '/lib/private/PhoneNumberUtil.php',
         'OC\\PreviewManager' => __DIR__ . '/../../..' . '/lib/private/PreviewManager.php',
         'OC\\PreviewNotAvailableException' => __DIR__ . '/../../..' . '/lib/private/PreviewNotAvailableException.php',
@@ -2144,6 +2147,8 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\Share\\Constants' => __DIR__ . '/../../..' . '/lib/private/Share/Constants.php',
         'OC\\Share\\Helper' => __DIR__ . '/../../..' . '/lib/private/Share/Helper.php',
         'OC\\Share\\Share' => __DIR__ . '/../../..' . '/lib/private/Share/Share.php',
+        'OC\\SnowflakeId' => __DIR__ . '/../../..' . '/lib/private/SnowflakeId.php',
+        'OC\\SnowflakeIdGenerator' => __DIR__ . '/../../..' . '/lib/private/SnowflakeIdGenerator.php',
         'OC\\SpeechToText\\SpeechToTextManager' => __DIR__ . '/../../..' . '/lib/private/SpeechToText/SpeechToTextManager.php',
         'OC\\SpeechToText\\TranscriptionJob' => __DIR__ . '/../../..' . '/lib/private/SpeechToText/TranscriptionJob.php',
         'OC\\StreamImage' => __DIR__ . '/../../..' . '/lib/private/StreamImage.php',

lib/private/SnowflakeId.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OC;
+
+use OCP\ISnowflakeId;
+use Override;
+
+/**
+ * Nextcloud Snowflake ID
+ *
+ * Get information about Snowflake Id
+ *
+ * @since 33.0.0
+ */
+final class SnowflakeId implements ISnowflakeId {
+	private int $seconds = 0;
+	private int $milliseconds = 0;
+	private bool $isCli = false;
+	/** @var int<0, 511> */
+	private int $serverId = 0;
+	/** @var int<0, 4095> */
+	private int $sequenceId = 0;
+
+	public function __construct(
+		private readonly int|float $id,
+	) {
+	}
+
+	private function decode(): void {
+		if ($this->seconds !== 0) {
+			return;
+		}
+
+		if (PHP_INT_SIZE === 8) {
+			// 64 bits handling
+			$id = (int)$this->id;
+			$firstHalf = $id >> 32;
+			$secondHalf = $id & 0xFFFFFFFF;
+		} else {
+			// 32 bits handling
+			$id = hex2bin(sprintf('%016x', $this->id));
+			assert($id !== false);
+			$id = unpack('Lfirst/Lsecond', $id);
+			assert($id !== false);
+			$firstHalf = $id['first'];
+			$secondHalf = $id['second'];
+		}
+
+		// First half without first bit is seconds
+		$this->seconds = $firstHalf & 0x7FFFFFFF;
+
+		// Decode second half
+		$this->milliseconds = $secondHalf >> 22;
+		$this->serverId = ($secondHalf >> 13) & 0x1FF;
+		$this->isCli = (bool)(($secondHalf >> 12) & 0x1);
+		$this->sequenceId = $secondHalf & 0xFFF;
+	}
+
+	#[Override]
+	public function isCli(): bool {
+		return $this->isCli;
+	}
+
+	#[Override]
+	public function numeric(): int|float {
+		return $this->id;
+	}
+
+	#[Override]
+	public function seconds(): int {
+		$this->decode();
+		return $this->seconds;
+	}
+
+	#[Override]
+	public function milliseconds(): int {
+		$this->decode();
+		return $this->milliseconds;
+	}
+
+	#[Override]
+	public function createdAt(): float {
+		$this->decode();
+		return $this->seconds + self::TS_OFFSET + ($this->milliseconds / 1000);
+	}
+
+	#[Override]
+	public function serverId(): int {
+		$this->decode();
+		return	$this->serverId;
+	}
+
+	#[Override]
+	public function sequenceId(): int {
+		$this->decode();
+		return $this->sequenceId;
+	}
+}

lib/private/SnowflakeIdGenerator.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OC;
+
+/**
+ * Nextcloud Snowflake ID generator
+ *
+ * Generates unique ID for database
+ *
+ * @since 33.0.0
+ */
+final class SnowflakeIdGenerator {
+	public function __invoke(): int|float {
+		// Time related
+		$microtime = microtime(true);
+		$seconds = ((int)$microtime) - SnowflakeId::TS_OFFSET;
+		$milliseconds = ((int)($microtime * 1000)) % 1000;
+
+		$serverId = $this->getServerId() & 0x1FF; // Keep 9 bits
+		$isCli = (int)$this->isCli(); // 1 bit
+		$sequenceId = $this->getSequenceId($seconds, $milliseconds); //  12 bits
+		if ($sequenceId > 0xFFF) {
+			// Throttle a bit, wait for next millisecond
+			usleep(1000);
+			return $this();
+		}
+
+		$firstHalf = $seconds & 0x7FFFFFFF;
+		$secondHalf = (($milliseconds & 0x3FF) << 22) | ($serverId << 13) | ($isCli << 12) | $sequenceId;
+		if (PHP_INT_SIZE === 8) {
+			return $firstHalf << 32 | $secondHalf;
+		}
+
+		// Fallback for 32 bits systems
+		return hexdec(bin2hex(pack('LL', $firstHalf, $secondHalf)));
+	}
+
+	private function getServerId(): int {
+		return crc32(gethostname() ?: random_bytes(8));
+	}
+
+	private function isCli() {
+		return PHP_SAPI === 'cli';
+	}
+
+	private function getSequenceId(int $seconds, int $milliseconds): int {
+		if ($this->isCli()) {
+			// APCu cache isn’t shared between CLI processes
+			return random_int(0, 0xFFF - 1);
+		}
+
+		if (function_exists('apcu_inc')) {
+			$key = 'sequence:' . $seconds . ':' . $milliseconds;
+			$sequenceId = apcu_inc($key, ttl: 1);
+			if ($sequenceId === false) {
+				throw new \Exception('Failed to generate SnowflakeId with APCu');
+			}
+
+			return $sequenceId;
+		}
+
+		// TODO Implement file fallback?
+		throw new \Exception('Failed to get sequence Id');
+	}
+}

lib/public/ISnowflakeId.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP;
+
+/**
+ * Nextcloud ID generator
+ *
+ * Generates unique ID
+ * @since 33.0.0
+ */
+interface ISnowflakeId {
+	public const TS_OFFSET = 1759276800; // 2025-10-01 00:00:00
+
+	/**
+	 * Returns sequence ID as int (64 bits servers) or float (32 bits servers)
+	 *
+	 * This method is suitable to store Sequence Id in database.
+	 * Use BIGINT (8 bytes)
+	 *
+	 * @since 33.0
+	 */
+	public function numeric(): int|float;
+
+	/**
+	 * Returns whether the SequenceId was created in CLI or not (eg. FPM, Apache)
+	 *
+	 * @since 33.0
+	 */
+	public function isCli(): bool;
+
+	/**
+	 * Returns the number of seconds after self::TS_OFFSET
+	 *
+	 * Creation time of the sequence ID since self::TS_OFFSET
+	 *
+	 * @since 33.0
+	 */
+	public function seconds(): int;
+
+	/**
+	 * Returns the number of milliseconds of creation
+	 *
+	 * @since 33.0
+	 */
+	public function milliseconds(): int;
+
+	/**
+	 * Returns full millisecond creation timestamp
+	 *
+	 * @since 33.0
+	 */
+	public function createdAt(): float;
+
+	/**
+	 * Returns server ID (encoded on 9 bits)
+	 *
+	 * @return int<0, 511>
+	 * @since 33.0
+	 */
+	public function serverId(): int;
+
+	/**
+	 * Returns sequence ID (encoded on 12 bits)
+	 *
+	 * @return int<0, 4095>
+	 * @since 33.0
+	 */
+	public function sequenceId(): int;
+}

lib/public/ISnowflakeIdGenerator.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP;
+
+/**
+ * Nextcloud ID generator
+ *
+ * Generates unique ID
+ * @since 33.0.0
+ */
+interface ISnowflakeIdGenerator {
+	public function __invoke(): int|float;
+}

tests/lib/SnowflakeIdGeneratorTest.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace Test;
+
+use OC\SnowflakeIdGenerator;
+
+/**
+ * @package Test
+ */
+class SnowflakeIdGeneratorTest extends TestCase {
+	public function testGenerator(): void {
+		$generator = new SnowflakeIdGenerator();
+
+		$snowflakeId = $generator();
+		$this->assertGreaterThan(0x100000000, $snowflakeId);
+		if (PHP_INT_SIZE < 8) {
+			$this->assertIsFloat($snowflakeId);
+		} else {
+			$this->assertIsInt($snowflakeId);
+		}
+	}
+}