fixup! refactor!: Rename Snowflake Generator and Decoder and introduc…

…e the Snowflake DTO

lib/public/Snowflake/ISnowflakeDecoder.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP\Snowflake;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+/**
+ * Nextcloud Snowflake ID decoder
+ *
+ * @see \OCP\Snowflake\ISnowflakeGenerator for format
+ * @since 33.0.0
+ */
+#[Consumable(since: '33.0.0')]
+interface ISnowflakeDecoder {
+	/**
+	 * Decode information contained into Snowflake ID
+	 *
+	 * It includes:
+	 *  - server ID: identify server on which ID was generated
+	 *  - sequence ID: sequence number (number of snowflakes generated in the same second)
+	 *  - createdAt: timestamp at which ID was generated
+	 *  - isCli: if ID was generated using CLI or not
+	 *
+	 * @return Snowflake
+	 * @since 33.0
+	 */
+	public function decode(string $snowflakeId): Snowflake;
+}

lib/public/Snowflake/ISnowflakeGenerator.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace OCP\Snowflake;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+/**
+ * Nextcloud Snowflake ID generator
+ *
+ * Customized version of Snowflake IDs for Nextcloud:
+ *   1 bit : Unused, always 0, avoid issue with PHP signed integers.
+ *	31 bits: Timestamp from 2025-10-01. Allows to store a bit more than 68 years. Allows to find creation time.
+ *	10 bits: Milliseconds (between 0 and 999)
+ *	 9 bits: Server ID, identify server which generated the ID (between 0 and 1023)
+ *	 1 bit : CLI or Web (0 or 1)
+ *	12 bits: Sequence ID, usually a serial number of objects created in the same number on same server (between 0 and 4095)
+ *
+ * @since 33.0.0
+ */
+#[Consumable(since: '33.0.0')]
+interface ISnowflakeGenerator {
+
+	/**
+	 * Offset applied on timestamps to keep it short
+	 * Start from 2025-10-01 at 00:00:00
+	 *
+	 * @since 33.0
+	 */
+	public const TS_OFFSET = 1759276800;
+
+	/**
+	 * Get a new Snowflake ID.
+	 *
+	 * Each call to this method is guaranteed to return a different ID.
+	 *
+	 * @since 33.0
+	 */
+	public function nextId(): string;
+}

lib/public/Snowflake/Snowflake.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Snowflake;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+/**
+ * Nextcloud Snowflake DTO
+ *
+ * @since 33.0.0
+ */
+#[Consumable(since: '33.0.0')]
+final readonly class Snowflake {
+	/**
+	 * @psalm-param int<0,1023> $serverId
+	 * @psalm-param int<0,4095> $sequenceId
+	 * @psalm-param non-negative-int $seconds
+	 * @psalm-param int<0,999> $milliseconds
+	 */
+	public function __construct(
+		private int $serverId,
+		private int $sequenceId,
+		private bool $isCli,
+		private int $seconds,
+		private int $milliseconds,
+		private \DateTimeImmutable $createdAt,
+	) {
+	}
+
+	/**
+	 * @psalm-return int<0,1023>
+	 */
+	public function getServerId(): int {
+		return $this->serverId;
+	}
+
+	/**
+	 * @psalm-return int<0,4095>
+	 */
+	public function getSequenceId(): int {
+		return $this->sequenceId;
+	}
+
+	public function isCli(): bool {
+		return $this->isCli;
+	}
+
+	/**
+	 * @psalm-return non-negative-int
+	 */
+	public function getSeconds(): int {
+		return $this->seconds;
+	}
+
+	/**
+	 * @psalm-return  int<0,999>
+	 */
+	public function getMilliseconds(): int {
+		return $this->milliseconds;
+	}
+
+	public function getCreatedAt(): \DateTimeImmutable {
+		return $this->createdAt;
+	}
+}