Skip to main content

sigid_enterprise/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! # SigID Enterprise
4//!
5//! Enterprise-grade ID generator for distributed systems.
6//!
7//! Features:
8//! - Worker ID coordination (static/dynamic)
9//! - UUID/ULID conversion
10//! - ID inspection and metadata extraction
11//!
12//! # Example
13//! ```
14//! use sigid_enterprise::{Generator, WorkerId};
15//!
16//! let mut gen = Generator::new()
17//!     .with_worker_id(WorkerId::new(42).unwrap())
18//!     .build();
19//!
20//! let id = gen.generate(1234567890).unwrap();
21//! println!("ID: {}", id);
22//! // With the `uuid` feature: `use sigid_enterprise::SigIdUuidExt; id.to_uuid()`
23//! ```
24
25#![cfg_attr(not(feature = "std"), no_std)]
26#![warn(missing_docs, missing_debug_implementations)]
27
28extern crate alloc;
29
30pub mod inspect;
31pub mod worker;
32
33#[cfg(feature = "uuid")]
34pub mod convert;
35
36pub use inspect::{inspect, InspectResult};
37pub use worker::WorkerId;
38
39#[cfg(feature = "uuid")]
40pub use convert::SigIdUuidExt;
41
42#[cfg(feature = "ulid")]
43pub use convert::ulid::SigIdUlidExt;
44
45/// Re-export core and flexible types
46pub use sigid_core::{Error, Result, SigId26, COUNTER_MAX, EPOCH};
47pub use sigid_flexible::{Alphabet, Generator as FlexibleGenerator};
48
49/// Enterprise generator builder with persistent state
50#[derive(Debug, Clone)]
51pub struct Generator {
52    flexible: FlexibleGenerator,
53    worker_id: WorkerId,
54}
55
56impl Generator {
57    /// Create new enterprise generator
58    pub fn new() -> Self {
59        Self {
60            flexible: FlexibleGenerator::new(),
61            worker_id: WorkerId::from(0),
62        }
63    }
64
65    /// Set worker ID (используется в битовой схеме, а не как сид)
66    pub fn with_worker_id(mut self, worker_id: WorkerId) -> Self {
67        self.worker_id = worker_id;
68        self.flexible = self.flexible.worker_id(worker_id.value());
69        self
70    }
71
72    /// Set seed for the generator
73    pub fn with_seed(mut self, seed: u64) -> Self {
74        self.flexible = self.flexible.with_seed(seed);
75        self
76    }
77
78    /// Take the random part of every ID from the OS CSPRNG instead of the
79    /// seeded Xorshift (the seed then no longer matters). Requires the
80    /// `secure` feature. IDs become unpredictable, but an ID is still an
81    /// identifier, not a secret: do not use it as a token or reset link.
82    #[cfg(feature = "secure")]
83    pub fn secure(mut self) -> Self {
84        self.flexible = self.flexible.secure();
85        self
86    }
87
88    /// Set worker ID from environment (std only)
89    #[cfg(feature = "std")]
90    pub fn with_worker_id_from_env(mut self) -> Self {
91        self.worker_id = WorkerId::zero_config();
92        self.flexible = self.flexible.worker_id(self.worker_id.value());
93        self
94    }
95
96    /// Set ID length
97    pub fn length(mut self, length: usize) -> Self {
98        self.flexible = self.flexible.length(length);
99        self
100    }
101
102    /// Set alphabet
103    pub fn alphabet(mut self, alphabet: Alphabet) -> Self {
104        self.flexible = self.flexible.alphabet(alphabet);
105        self
106    }
107
108    /// Enable checksum
109    pub fn with_checksum(mut self, enabled: bool) -> Self {
110        self.flexible = self.flexible.with_checksum(enabled);
111        self
112    }
113
114    /// Build the generator (consumes builder)
115    pub fn build(self) -> Self {
116        self
117    }
118
119    /// Generate ID from timestamp
120    pub fn generate(&mut self, ms: u64) -> Result<SigId26> {
121        self.flexible.generate_raw(ms)
122    }
123
124    /// Generate ID with current time (std only)
125    #[cfg(feature = "std")]
126    pub fn now(&mut self) -> Result<SigId26> {
127        use std::time::{SystemTime, UNIX_EPOCH};
128        let ms = SystemTime::now()
129            .duration_since(UNIX_EPOCH)
130            .unwrap_or_default()
131            .as_millis() as u64;
132        self.generate(ms)
133    }
134
135    /// Get current worker ID
136    pub fn worker_id(&self) -> WorkerId {
137        self.worker_id
138    }
139}
140
141impl Default for Generator {
142    fn default() -> Self {
143        Self::new()
144    }
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150
151    #[test]
152    fn test_generator_new() {
153        let mut gen = Generator::new();
154        let id = gen.generate(1234567890).unwrap();
155        assert!(id.is_valid());
156    }
157
158    #[test]
159    fn test_generator_with_worker_id() {
160        let worker = WorkerId::new(42).unwrap();
161        let mut gen = Generator::new().with_worker_id(worker);
162        assert_eq!(gen.worker_id(), worker);
163
164        let id = gen.generate(1234567890).unwrap();
165        assert_eq!(id.worker_id(), worker.value());
166    }
167
168    #[test]
169    #[cfg(feature = "std")]
170    fn test_generator_worker_from_env() {
171        let mut gen = Generator::new().with_worker_id_from_env();
172        let worker_val = gen.worker_id().value();
173
174        let id = gen.generate(1234567890).unwrap();
175        assert_eq!(id.worker_id(), worker_val);
176    }
177
178    #[test]
179    #[cfg(feature = "uuid")]
180    fn test_generator_uuid_conversion() {
181        use super::SigIdUuidExt;
182        let mut gen = Generator::new();
183        let id = gen.generate(1234567890).unwrap();
184        let uuid = id.to_uuid();
185        let converted = SigId26::from_uuid(uuid);
186        assert_eq!(id.as_bytes(), converted.as_bytes());
187    }
188
189    #[test]
190    fn test_generator_timestamp() {
191        let mut gen = Generator::new();
192        let ms = 1700000000000;
193        let id = gen.generate(ms).unwrap();
194        assert_eq!(id.timestamp_ms(), ms);
195    }
196
197    #[test]
198    fn test_generator_counter_increment() {
199        let mut gen = Generator::new();
200        let ms = 1234567890;
201
202        let id1 = gen.generate(ms).unwrap();
203        let id2 = gen.generate(ms).unwrap();
204
205        assert_eq!(id2.counter(), id1.counter() + 1);
206    }
207
208    #[test]
209    fn test_with_seed() {
210        let mut gen = Generator::new().with_seed(0x123456789abcdef);
211        let id = gen.generate(1234567890).unwrap();
212        assert!(id.is_valid());
213    }
214
215    #[cfg(feature = "secure")]
216    #[test]
217    fn test_secure_builder_is_not_reproducible_and_keeps_worker() {
218        let ms = 1_700_000_000_000;
219        let mk = || Generator::new()
220            .with_worker_id(WorkerId::new(9).unwrap())
221            .with_seed(7)
222            .secure()
223            .build();
224        let (mut a, mut b) = (mk(), mk());
225        let (ia, ib) = (a.generate(ms).unwrap(), b.generate(ms).unwrap());
226        assert_eq!(ia.worker_id(), 9);
227        assert_ne!(ia, ib);
228    }
229}