odoid 1.0.0

Deterministic mixed-radix ID encoding — maps integers to 6, 7, or 8-character alphanumeric strings. Ambiguous characters I, L, O are excluded.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! OdoIDGenerator — distributed monotonic generator.

use std::time::{SystemTime, UNIX_EPOCH};

use crate::charsets::MAX;
use crate::decode::decode;
use crate::encode::{assert_length, encode};
use crate::errors::{OdoError, UnsupportedLengthError};

/// Configuration for [`OdoIDGenerator`].
#[derive(Debug, Clone)]
pub struct GeneratorConfig {
    /// Logical namespace for this generator. Defaults to `"default"`.
    pub namespace: String,
    /// OdoID string length. Must be 6, 7, or 8. Defaults to `6`.
    pub length: usize,
    /// Millisecond epoch used as the time origin. `None` means use now.
    pub epoch: Option<u64>,
}

impl Default for GeneratorConfig {
    fn default() -> Self {
        Self {
            namespace: "default".into(),
            length: 6,
            epoch: None,
        }
    }
}

/// Value returned by [`OdoIDGenerator::next`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OdoIDResult {
    pub id: String,
    pub n: u64,
    pub length: usize,
    pub namespace: String,
}

/// A distributed monotonic generator that produces OdoID strings driven by a
/// namespace-scoped, time-seeded pseudo-random integer.
///
/// The generator guarantees that rapid successive calls within the same
/// millisecond tick produce distinct values via a monotonically incrementing
/// sequence counter. Output is always in `[0, capacity)` so [`encode`] never
/// returns [`OdoError::Overflow`] internally.
pub struct OdoIDGenerator {
    pub namespace: String,
    pub length: usize,
    pub capacity: u64,
    epoch: u64,
    sequence: u64,
    last_tick: u64,
}

fn now_ms() -> u64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .expect("system time before UNIX epoch")
        .as_millis() as u64
}

/// FNV-1a 32-bit hash.
/// Constants are normative: offset basis = 2166136261, prime = 16777619.
fn fnv1a32(value: &str) -> u64 {
    let mut h: u32 = 2166136261;
    for byte in value.bytes() {
        h ^= u32::from(byte);
        h = h.wrapping_mul(16777619);
    }
    u64::from(h)
}

impl OdoIDGenerator {
    /// Creates a new [`OdoIDGenerator`] from `config`.
    ///
    /// # Errors
    /// Returns [`UnsupportedLengthError`] if `config.length` is not 6, 7, or 8.
    pub fn new(config: GeneratorConfig) -> Result<Self, UnsupportedLengthError> {
        assert_length(config.length)?;
        let epoch = config.epoch.unwrap_or_else(now_ms);
        Ok(Self {
            namespace: config.namespace,
            length: config.length,
            capacity: MAX[config.length],
            epoch,
            sequence: 0,
            last_tick: 0,
        })
    }

    fn tick(&self) -> u64 {
        now_ms().saturating_sub(self.epoch)
    }

    /// Returns the next raw integer `n` in `[0, capacity)`.
    /// Exposed for testing and low-level use.
    pub fn next_n(&mut self) -> u64 {
        let tick = self.tick();

        if tick == self.last_tick {
            self.sequence += 1;
        } else {
            self.sequence = 0;
            self.last_tick = tick;
        }

        let key = format!("{}|{}", self.namespace, tick);
        let mut seed = fnv1a32(&key);
        seed ^= seed << 13;
        seed ^= seed >> 7;
        seed ^= seed << 17;

        (seed + self.sequence) % self.capacity
    }

    /// Generates and returns the next OdoID.
    pub fn next(&mut self) -> Result<OdoIDResult, OdoError> {
        let n = self.next_n();
        let id = encode(n, self.length)?;
        Ok(OdoIDResult {
            id,
            n,
            length: self.length,
            namespace: self.namespace.clone(),
        })
    }

    /// Encodes `n` using this generator's configured length.
    pub fn encode(&self, n: u64) -> Result<String, OdoError> {
        encode(n, self.length)
    }

    /// Decodes an OdoID string to its originating integer.
    pub fn decode(&self, id: &str) -> Result<u64, OdoError> {
        decode(id)
    }
}