Configuration & Bit Allocation

TimeSeed features a highly customizable configuration system allowing precise bit allocation, custom starting epochs, clock drift tolerances, and overflow handling.

TimeSeedConfig Class

The configuration dataclass for the TimeSeed generator.

Initialization Parameters

• bit_allocation (BitAllocation): Bit division for components. Defaults to default bit allocation.
• epoch_start_ms (int): Custom starting epoch in milliseconds. Defaults to 1717199999000 (June 2024).
• machine_id (int, optional): Explicit machine ID. Resolved from environment variable TIMESEED_MACHINE_ID if not provided.
• datacenter_id (int, optional): Explicit datacenter ID. Resolved from environment variable TIMESEED_DATACENTER_ID if not provided.
• clock_backward_tolerance_ms (int): Milliseconds allowed for clock drift/backward movement. Defaults to 10.
• sequence_overflow_wait (bool): If True, wait until the next millisecond on sequence overflow. If False, raise a SequenceOverflowError. Defaults to True.
• hex_uppercase (bool): Forces uppercase format for hexadecimal conversions. Defaults to True.

Methods

• create_custom(timestamp_bits: int, machine_bits: int, datacenter_bits: int, sequence_bits: int) -> TimeSeedConfig: Quickly helper to initialize custom bit allocations.

---

BitAllocation Dataclass

Defines the number of bits allocated to each component of the 128-bit ID space.

• timestamp_bits (int): Bits for timestamp. Must be at least 32.
• machine_bits (int): Bits for machine identifier. Must be at least 1.
• datacenter_bits (int): Bits for datacenter identifier. Must be at least 1.
• sequence_bits (int): Bits for sequence counter. Must be at least 8.

---

Preset Configurations

PresetConfigs.high_throughput() -> TimeSeedConfig

Optimized for high-throughput nodes. Allocates more bits to sequence counter.

• Allocation: 44 timestamp bits, 12 machine bits, 8 datacenter bits, 64 sequence bits.

PresetConfigs.long_lifespan() -> TimeSeedConfig

Optimized for long-lived systems where clock precision over years is critical.

• Allocation: 60 timestamp bits, 12 machine bits, 8 datacenter bits, 48 sequence bits.

PresetConfigs.many_datacenters() -> TimeSeedConfig

Optimized for massive scale deployments across many globally distributed datacenters.

• Allocation: 44 timestamp bits, 16 machine bits, 24 datacenter bits, 44 sequence bits.

PresetConfigs.small_scale() -> TimeSeedConfig

Optimized for local/smaller deployments where machine count is minimal.

• Allocation: 48 timestamp bits, 8 machine bits, 4 datacenter bits, 32 sequence bits.