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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
use std::thread::sleep;
use std::time::{Duration, SystemTime, SystemTimeError, UNIX_EPOCH};

pub type SequenceGeneratorSystemTimeError = SystemTimeError;

fn timestamp_from_custom_epoch(
    custom_epoch: SystemTime,
    micros_ten_power: u8,
) -> Result<u64, SequenceGeneratorSystemTimeError> {
    let timestamp;
    let mut micros_ten_power = micros_ten_power;
    if micros_ten_power >= 3 {
        timestamp = SystemTime::now().duration_since(custom_epoch)?.as_millis();
        micros_ten_power -= 3;
    } else {
        timestamp = SystemTime::now().duration_since(custom_epoch)?.as_micros();
    }
    match micros_ten_power {
        0 => Ok(timestamp as u64),
        _ => Ok((timestamp as u64) / (10 as u64).pow(micros_ten_power.into())),
    }
}

#[derive(Debug)]
pub struct SequenceProperties {
    pub unused_bits: u8,
    pub timestamp_bits: u8,
    pub node_id_bits: u8,
    pub sequence_bits: u8,
    pub custom_epoch: SystemTime,
    current_timestamp: Option<u64>,
    last_timestamp: Option<u64>,
    pub micros_ten_power: u8,
    pub node_id: u16,
    pub sequence: u16,
    pub max_sequence: u16,
    pub backoff_cooldown_start_ns: u64,
    partial_cached_id: Option<u64>,
}

impl SequenceProperties {
    pub fn new(
        custom_epoch: SystemTime,
        node_id_bits: u8,
        node_id: u16,
        sequence_bits: u8,
        micros_ten_power: u8,
        unused_bits: u8,
        backoff_cooldown_start_ns: u64,
    ) -> Self {
        let timestamp_bits = (64 as u8)
            .checked_sub(sequence_bits)
            .expect(&format!(
                "Error: Sequence bits is too large '{}'", sequence_bits))
            .checked_sub(node_id_bits)
            .expect(&format!(
                "Error: Sum of bits is too large, maximum value 64. Node ID bits '{}', Sequence bits '{}'",
                node_id_bits, sequence_bits
            ))
            .checked_sub(unused_bits)
            .expect(&format!(
                "Error: Sum of bits is too large, maximum value 64. Unused bits '{}', Sequence bits '{}', Node ID bits '{}'", 
                unused_bits, sequence_bits, node_id_bits
            ));
        SequenceProperties {
            custom_epoch,
            timestamp_bits,
            node_id_bits,
            sequence_bits,
            current_timestamp: None,
            last_timestamp: None,
            micros_ten_power,
            node_id,
            unused_bits,
            sequence: 0,
            max_sequence: (2 as u16).pow(sequence_bits.into()),
            backoff_cooldown_start_ns,
            partial_cached_id: None,
        }
    }
}

pub fn generate_id(
    properties: &mut SequenceProperties,
) -> Result<u64, SequenceGeneratorSystemTimeError> {
    properties.last_timestamp = properties.current_timestamp;
    properties.current_timestamp = Some(timestamp_from_custom_epoch(
        properties.custom_epoch,
        properties.micros_ten_power,
    )?);
    if let Some(last_timestamp) = properties.last_timestamp {
        let current_timestamp = properties.current_timestamp.unwrap();
        if current_timestamp < last_timestamp {
            println!("Error: System Clock moved backwards. Current timestamp '{}' is earlier than last registered '{}'.", 
                current_timestamp, last_timestamp);
            if properties.sequence == properties.max_sequence {
                wait_next_timestamp(
                    last_timestamp,
                    properties.custom_epoch,
                    properties.micros_ten_power,
                    properties.backoff_cooldown_start_ns,
                )?;
                // After timestamp changed reset to start a new sequence
                properties.sequence = 0;
            } else {
                wait_until_last_timestamp(
                    last_timestamp,
                    properties.custom_epoch,
                    properties.micros_ten_power,
                    properties.backoff_cooldown_start_ns,
                )?;
            }
            properties.current_timestamp = Some(timestamp_from_custom_epoch(
                properties.custom_epoch,
                properties.micros_ten_power,
            )?);
        } else if properties.current_timestamp.unwrap() != last_timestamp {
            properties.sequence = 0;
        }
    }
    let new_id = to_id(properties);
    properties.sequence += 1;
    if properties.sequence == properties.max_sequence {
        wait_next_timestamp(
            properties.last_timestamp.unwrap(),
            properties.custom_epoch,
            properties.micros_ten_power,
            properties.backoff_cooldown_start_ns,
        )?;
        properties.current_timestamp = Some(timestamp_from_custom_epoch(
            properties.custom_epoch,
            properties.micros_ten_power,
        )?);
        // After timestamp changed reset to start a new sequence
        properties.sequence = 0;
    }
    Ok(new_id)
}

fn wait_next_timestamp(
    last_timestamp: u64,
    custom_epoch: SystemTime,
    micros_ten_power: u8,
    backoff_cooldown_start_ns: u64,
) -> Result<(), SequenceGeneratorSystemTimeError> {
    let mut current_timestamp = timestamp_from_custom_epoch(custom_epoch, micros_ten_power)?;
    let backoff_cooldown_ns: u64 = backoff_cooldown_start_ns;
    while current_timestamp <= last_timestamp {
        sleep(Duration::from_nanos(backoff_cooldown_ns));
        current_timestamp = timestamp_from_custom_epoch(custom_epoch, micros_ten_power)?;
        // Double the cooldown wait period (exponential backoff)
        backoff_cooldown_ns
            .checked_add(backoff_cooldown_ns)
            .expect(&format!(
                "Error: Cannot double backoff cooldown, maximum value reached '{}'",
                backoff_cooldown_ns
            ));
    }
    Ok(())
}

fn wait_until_last_timestamp(
    last_timestamp: u64,
    custom_epoch: SystemTime,
    micros_ten_power: u8,
    backoff_cooldown_start_ns: u64,
) -> Result<(), SequenceGeneratorSystemTimeError> {
    let mut current_timestamp = timestamp_from_custom_epoch(custom_epoch, micros_ten_power)?;
    let backoff_cooldown_ns: u64 = backoff_cooldown_start_ns;
    while current_timestamp < last_timestamp {
        sleep(Duration::from_nanos(backoff_cooldown_ns));
        current_timestamp = timestamp_from_custom_epoch(custom_epoch, micros_ten_power)?;
        // Double the cooldown wait period (exponential backoff)
        backoff_cooldown_ns
            .checked_add(backoff_cooldown_ns)
            .expect(&format!(
                "Error: Cannot double backoff cooldown, maximum value reached '{}'",
                backoff_cooldown_ns
            ));
    }
    Ok(())
}

fn to_id_cached(properties: &mut SequenceProperties) -> u64 {
    let mut id = properties.partial_cached_id.unwrap();
    id |= ((properties.sequence as u64) << properties.node_id_bits) as u64;
    id
}

fn to_id(properties: &mut SequenceProperties) -> u64 {
    if properties.sequence == 0 {
        cache_partial_id(properties);
    }
    to_id_cached(properties)
}

fn cache_partial_id(properties: &mut SequenceProperties) {
    let timestamp_shift_bits = properties.node_id_bits + properties.sequence_bits;
    let mut id = properties.current_timestamp.unwrap() << timestamp_shift_bits;
    id |= properties.node_id as u64;
    properties.partial_cached_id = Some(id);
}

pub fn decode_id_unix_epoch_micros(id: u64, properties: &SequenceProperties) -> u64 {
    let id_timestamp_custom_epoch = (id << (properties.unused_bits))
        >> (properties.node_id_bits + properties.sequence_bits + properties.unused_bits);
    let timestamp_micros =
        id_timestamp_custom_epoch * (10 as u64).pow(properties.micros_ten_power as u32);
    properties
        .custom_epoch
        .duration_since(UNIX_EPOCH)
        .expect(&format!(
            "Error: Could not calculate difference between timestamp decoded from ID and Unix epoch."
        ))
        .checked_add(Duration::from_micros(timestamp_micros))
        .expect(&format!(
            "Error: Could not add the timestamp decoded from ID to the provided custom epoch."
        ))
        .as_micros() as u64
}

pub fn decode_node_id(id: u64, properties: &SequenceProperties) -> u16 {
    ((id << (properties.unused_bits + properties.timestamp_bits + properties.sequence_bits))
        >> (properties.sequence_bits + properties.timestamp_bits + properties.unused_bits))
        as u16
}

pub fn decode_sequence_id(id: u64, properties: &SequenceProperties) -> u16 {
    ((id << (properties.unused_bits + properties.timestamp_bits))
        >> (properties.unused_bits + properties.timestamp_bits + properties.node_id_bits))
        as u16
}

#[cfg(test)]
mod tests {
    #[test]
    fn timestamp_from() {
        // Perform consistency tests for datetime calculation from a custom epoch
        // First case: Compare system time against custom epoch set to UNIX_EPOCH
        // Second case: Set CUSTOM_EPOCH to test start time and compare timestamp
        // calculation against known sleep duration interval
        use super::*;
        let time_now = SystemTime::now();
        let millis_start = time_now
            .duration_since(UNIX_EPOCH)
            .expect("Error: Failed to get current time as duration from epoch.")
            .as_millis();
        sleep(Duration::from_millis(50));
        // Test UNIX EPOCH
        let millis_after = timestamp_from_custom_epoch(UNIX_EPOCH, 3).unwrap_or_else(
            |error| {
                panic!(format!(
                    "SequenceGeneratorSystemTimeError: Failed to get timestamp from custom epoch {:?}, difference {:?}",
                    UNIX_EPOCH, (error).duration()
                ))
            });
        // More than expected 50ms. Upper boundary cannot be ascertained as Normal distribution
        // CPU low-power states and/or older hardware can cause signifficant differences.
        // (although rather then a Normal distribution, it is instead the case that a Pareto
        // distribution applies, making it impossible to set high enough value for the test
        // not to fail on ocassion)
        let substracted_times = millis_after.checked_sub(millis_start as u64).unwrap();
        println!("Too small time difference between times calculated\nfrom UNIX_EPOCH using independent functions.\n\nEpoch System Time - Time Difference w/Epoch = {} ms,\nexpected greater or equals than sleep interval 50 ms.\n", substracted_times);
        assert!(substracted_times >= 50);
        // If too big upper boundary there could be numerical errors.
        assert!((millis_after.checked_sub(millis_start as u64).unwrap()) < 90);
        // Test a CUSTOM EPOCH in tenths of a millisecond
        let custom_epoch = UNIX_EPOCH
            .checked_add(Duration::from_millis(millis_start as u64))
            .expect("Error: Failed to create custom epoch.");
        let tenths_millis_custom_epoch_time = timestamp_from_custom_epoch(custom_epoch, 2).unwrap_or_else(
            |error| {
                panic!(format!(
                    "SequenceGeneratorSystemTimeError: Failed to get current timestamp from custom epoch {:?}, difference {:?}",
                    UNIX_EPOCH, (error).duration()
                ))
            });
        // Wait a bit to prevent Option to call unwrap() on None below
        // If both timestamps are within small margin substraction of u64
        // can result in 'panicked at attempt to subtract with overflow'
        // and checked_sub returns None value
        sleep(Duration::from_millis(2));
        // convert elapsed time from microseconds into tenths of a millisecond (0,1ms = 100 mcs)
        let power_two: u32 = 2;
        let tenths_millis_elapsed_time = (time_now.elapsed().map_or_else(
            |error| {
                panic!(format!(
                    "SequenceGeneratorSystemTimeError: Failed to get elapsed time, difference {:?}",
                    (error).duration()
                ))
            },
            |duration| duration.as_micros() as u64,
        )) / (10 as u64).pow(power_two);
        let substracted_times = tenths_millis_elapsed_time
            .checked_sub(tenths_millis_custom_epoch_time)
            .unwrap();
        println!("Too high time difference between calculated time from\nCustom Epoch set at test start and actual elapsed\ntime since the test started.\n\nElapsed Time - Calculated Time Custom Epoch = {} mcs,\nexpected under 100 mcs\n\nPlease note that Pareto distribution applies and it\nis impossible to ensure a high enough difference for\nthe test not to fail on ocassion.\n\nReview only after ensuring repeated failures.\n", substracted_times);
        // Substract custom epoch result with Rust's own elapsed time
        // Upper boundary uncertainty set up high at 200mcs more than expected 511mcs as exponential
        // distribution, CPU low-power states and/or older hardware can cause signifficant differences.
        assert!(substracted_times < 200);
    }

    #[test]
    fn wait_until() {
        // Case where system clock is readjusted 50ms into the past
        // Current sequence wouldn't be exhausted but script cools down
        // until at least matching the previously stored timestamp.
        use super::*;
        let calculated_time_after_50ms: u64 = SystemTime::now()
            .checked_add(Duration::from_millis(50))
            .unwrap()
            .duration_since(UNIX_EPOCH)
            .expect("Error: Failed to get duration from epoch of timestamp 50ms into the future.")
            .as_millis() as u64;
        // Function itself serves as an sleep call if correct
        wait_until_last_timestamp(calculated_time_after_50ms, UNIX_EPOCH, 3, 1500).expect(
            &format!(
            "SequenceGeneratorSystemTimeError: Couldn't wait until timestamp '{}' with custom epoch '{:?}'",
            calculated_time_after_50ms, UNIX_EPOCH
        ),
        );
        // Wait a bit to prevent Option to call unwrap() on None below
        // If both timestamps are within small margin substraction of u64
        // can result in 'panicked at attempt to subtract with overflow'
        // and checked_sub returns None value.
        // Furthermore: It could also result in useless assert comparing
        // if an unsigned integer is higher or equal to zero
        sleep(Duration::from_millis(1));
        let time_after_50ms: u64 = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("Error: Failed to get current time as duration from epoch.")
            .as_millis() as u64;
        let substracted_times = time_after_50ms
            .checked_sub(calculated_time_after_50ms)
            .unwrap();
        assert!(substracted_times > 0);
        println!("Too high time difference while waiting for last timestamp\nafter clock moved backwards\n\nTime Calculated - Actual Time = {} ms, expected under 35 ms\n\nPlease note that Pareto distribution applies and it\nis impossible to ensure a high enough difference for\nthe test not to fail on ocassion.\n\nReview only after ensuring repeated failures.\n", substracted_times);
        // Assert an upper boundary to how high of a difference there can be.
        // If implementation is correct, the timestampts should be within few
        // ms of one another according to a Normal distribution in recent
        // hardware and normal CPU priority (although rather a Pareto
        // distribution applies, making it impossible to set a value high
        // enough for the test not to fail on ocassion)
        assert!(substracted_times < 35);
    }
    #[test]
    fn wait_next() {
        // Case where sequence would be exhausted and for that reason
        // script cools down until at least there exists a difference
        // between the current system time and the last known timestamp.
        use super::*;
        let calculated_time_after_10ms: u64 = SystemTime::now()
            .checked_add(Duration::from_millis(10))
            .expect("Error: Failed to 10ms to current timestamp.")
            .duration_since(UNIX_EPOCH)
            .expect("Error: Failed to get duration from epoch of timestamp 10ms into the future.")
            .as_millis() as u64;
        // Function itself serves as an sleep call if correct
        wait_next_timestamp(calculated_time_after_10ms, UNIX_EPOCH, 3, 1500).expect(&format!(
            "SequenceGeneratorSystemTimeError: Couldn't wait until timestamp '{}' with custom epoch '{:?}'",
            calculated_time_after_10ms, UNIX_EPOCH
        ));
        let time_after_11ms: u64 = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("Error: Failed to get current time as duration from epoch.")
            .as_millis() as u64;
        let substracted_times = time_after_11ms
            .checked_sub(calculated_time_after_10ms)
            .unwrap();
        assert!(substracted_times > 0);
        println!("Too high time difference while waiting for next timestamp\n\nNext timestamp - Last Timestamp = {} ms, expected under 35 ms\n\nPlease note that Pareto distribution applies and it\nis impossible to ensure a high enough difference for\nthe test not to fail on ocassion.\n\nReview only after ensuring repeated failures.\n", substracted_times);
        // Assert an upper boundary to how high of a difference there can be.
        // If implementation is correct, the timestampts should be within few
        // ms of one another according to a Normal distribution in recent
        // hardware and normal CPU priority (although rather a Pareto
        // distribution applies, making it impossible to set a value high
        // enough for the test not to fail on ocassion)
        assert!(substracted_times < 35);
    }
    #[test]
    fn gen_id() {
        use super::*;
        use rand::Rng;
        // timestamp with 39 bits
        let custom_epoch = UNIX_EPOCH;
        // 2^16 node id (up to 65536)
        let node_id_bits = 16;
        // Several unused bits
        let unused_bits = 7;
        // 2^2 sequence (up to 4)
        // To test sequence overflow and wait behaviour, sequence bits unrealistically low
        let sequence_bits = 2;
        // in centiseconds (10^4 mcs)
        let micros_ten_power = 4;
        let mut rng = rand::thread_rng();
        // 0..2^16-1
        let node_id = rng.gen_range(0..65535);
        // if stalled until next millisecond, begin exponential backoff at 1,5 mcs
        let backoff_cooldown_start_ns = 1_000_000;
        let mut properties = SequenceProperties::new(
            custom_epoch,
            node_id_bits,
            node_id,
            sequence_bits,
            micros_ten_power,
            unused_bits,
            backoff_cooldown_start_ns,
        );

        let last_timestamp = (SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("Error: Failed to get current time as duration from epoch.")
            .as_millis()
            / 10) as u64;
        let mut vector_ids: Vec<u64> = vec![0; 5];
        // Ensure a new fresh second
        wait_next_timestamp(
            last_timestamp,
            UNIX_EPOCH,
            micros_ten_power,
            backoff_cooldown_start_ns,
        )
        .expect(&format!(
            "SequenceGeneratorSystemTimeError: Couldn't wait until timestamp '{}' with custom epoch '{:?}'",
            last_timestamp, UNIX_EPOCH
        ));
        for element in vector_ids.iter_mut() {
            *element = generate_id(&mut properties).unwrap_or_else(
                |error| {
                    panic!(format!(
                        "SequenceGeneratorSystemTimeError: Failed to get timestamp from custom epoch {:?}, difference {:?}",
                        UNIX_EPOCH, (error).duration()
                    ))
                });
        }
        let decoded_timestamp = decode_id_unix_epoch_micros(vector_ids[0], &properties);
        assert!(((decoded_timestamp / 10_000) - (last_timestamp + 1)) < 15);
        let mut decoded_node_id = decode_node_id(vector_ids[0], &properties);
        assert_eq!(decoded_node_id, node_id);
        let mut decoded_seq_id = decode_sequence_id(vector_ids[0], &properties);
        assert_eq!(decoded_seq_id, 0);
        for index in 1..5 {
            decoded_seq_id = decode_sequence_id(vector_ids[index], &properties);
            assert_eq!(decoded_seq_id, (index as u16) % 4);
            decoded_node_id = decode_node_id(vector_ids[index], &properties);
            assert_eq!(decoded_node_id, node_id);
        }
        assert!(properties.current_timestamp.unwrap() - last_timestamp < 15);
    }
}