snowid 3.0.1

A Rust library for generating SnowID - a Snowflake-like timestamp-based distributed unique identifier
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

//! Configuration for `SnowID` generator
//!
#![allow(clippy::cast_possible_truncation)]

mod builder;

use std::error::Error;
use std::fmt;

pub use builder::SnowIDConfigBuilder;
use builder::{DEFAULT_CUSTOM_EPOCH, DEFAULT_NODE_BITS};

use crate::SnowID;

/// Errors related to `SnowIDConfig` builder validation
#[derive(Debug, Clone, PartialEq)]
pub enum SnowIDConfigError {
    /// Provided node bits are out of the supported range [6, 16]
    InvalidNodeBits { bits: u8 },
}

impl fmt::Display for SnowIDConfigError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            Self::InvalidNodeBits { bits } => {
                write!(f, "Node bits {bits} must be between 6 and 16")
            },
        }
    }
}

impl Error for SnowIDConfigError {}

/// Configuration for `SnowID` generator
/// Copy-optimized with const-evaluable fields
#[derive(Debug, Clone, Copy)]
#[repr(C)]
pub struct SnowIDConfig {
    node_bits: u8,
    custom_epoch: u64,
    timestamp_shift: u8,
    node_shift: u8,
    timestamp_mask: u64,
    node_mask: u16,
    sequence_mask: u16,
}

impl SnowIDConfig {
    /// Calculate mask for given number of bits
    pub(crate) const fn calculate_mask(bits: u8) -> u16 {
        ((1u32 << bits) - 1) as u16
    }

    /// Create new `SnowIDConfig` with given node bits
    const fn new(node_bits: u8, custom_epoch: u64) -> Self {
        let sequence_bits = SnowID::TOTAL_NODE_AND_SEQUENCE_BITS - node_bits;
        Self {
            node_bits,
            custom_epoch,
            timestamp_shift: SnowID::TOTAL_NODE_AND_SEQUENCE_BITS,
            node_shift: sequence_bits,
            timestamp_mask: (1u64 << SnowID::TIMESTAMP_BITS) - 1,
            node_mask: Self::calculate_mask(node_bits),
            sequence_mask: Self::calculate_mask(sequence_bits),
        }
    }

    /// Create a new configuration builder
    #[must_use]
    pub const fn builder() -> SnowIDConfigBuilder {
        SnowIDConfigBuilder::new()
    }

    #[must_use]
    pub const fn epoch(&self) -> u64 {
        self.custom_epoch
    }

    #[must_use]
    pub const fn node_bits(&self) -> u8 {
        self.node_bits
    }

    #[must_use]
    pub const fn sequence_bits(&self) -> u8 {
        SnowID::TOTAL_NODE_AND_SEQUENCE_BITS - self.node_bits
    }

    #[must_use]
    pub const fn max_node_id(&self) -> u16 {
        self.node_mask
    }

    #[must_use]
    pub const fn max_sequence_id(&self) -> u16 {
        self.sequence_mask
    }

    pub(crate) const fn timestamp_shift(&self) -> u8 {
        self.timestamp_shift
    }

    pub(crate) const fn node_shift(&self) -> u8 {
        self.node_shift
    }

    pub(crate) const fn timestamp_mask(&self) -> u64 {
        self.timestamp_mask
    }

    pub(crate) const fn node_mask(&self) -> u16 {
        self.node_mask
    }

    pub(crate) const fn sequence_mask(&self) -> u16 {
        self.sequence_mask
    }
}

impl Default for SnowIDConfig {
    fn default() -> Self {
        Self::new(DEFAULT_NODE_BITS, DEFAULT_CUSTOM_EPOCH)
    }
}