sfid 0.1.3

Distributed Snowflake ID generator with Redis-based auto machine ID allocation / 基于 Redis 自动分配机器号的分布式雪花 ID 生成器
Documentation

English | 中文

sfid : Distributed Snowflake ID Generator with Auto-Allocated Process ID

Features

  • Lock-free atomic ID generation
  • Configurable bit layout via Layout trait
  • Default: 36-bit timestamp (seconds), 11-bit process ID, 17-bit sequence
  • Redis-based automatic process ID allocation
  • Heartbeat mechanism with auto-release on crash
  • Clock drift tolerance (sequence borrowing + warning log)
  • Sequence exhaustion handling (timestamp advance)
  • Configurable epoch

Installation

cargo add sfid

With specific features:

cargo add sfid -F snowflake,auto_pid,parse

Quick Start

Manual Process ID

use sfid::{Snowflake, EPOCH};

let sf = Snowflake::new(EPOCH, 1);
let id = sf.next();
println!("{id}");

Auto-Allocated Process ID (Redis)

use sfid::{Snowflake, EPOCH};

#[tokio::main]
async fn main() -> sfid::Result<()> {
  let sf = Snowflake::auto("myapp", EPOCH).await?;
  let id = sf.next();
  println!("{id}");
  Ok(())
}

Parse ID

use sfid::parse;

let parsed = parse(id);
println!("ts: {}, pid: {}, seq: {}", parsed.ts, parsed.pid, parsed.seq);

Custom Bit Layout

use sfid::{Layout, Snowflake, parse_with};

struct MyLayout;
impl Layout for MyLayout {
  const TS_BITS: u32 = 41;
  const PID_BITS: u32 = 10;
  const SEQ_BITS: u32 = 13;
}

let sf = Snowflake::<MyLayout>::new(my_epoch, 1);
let id = sf.next();
let parsed = parse_with::<MyLayout>(id);

API Reference

Traits

Layout

Configurable bit layout for ID generation.

Constant Description
TS_BITS Timestamp bits
PID_BITS Process ID bits
SEQ_BITS Sequence bits
SEQ_MASK Derived: (1 << SEQ_BITS) - 1
PID_MASK Derived: (1 << PID_BITS) - 1
TS_MASK Derived: (1 << TS_BITS) - 1
TS_SHIFT Derived: SEQ_BITS + PID_BITS
MAX_PID Derived: 1 << PID_BITS

Constants

Name Type Description
EPOCH u64 Default epoch: 2025-12-22 00:00:00 UTC (seconds)

Structs

Snowflake<L: Layout = DefaultLayout>

ID generator with atomic state.

Method Description
new(epoch, pid) Create with manual process ID
auto(app, epoch) Create with Redis-allocated process ID
next() Generate next ID

DefaultLayout

Default bit layout: 36-11-17.

Pid

Process ID handle with heartbeat. Stops heartbeat on drop.

Method Description
id() Get allocated process ID

ParsedId

Parsed ID components.

Field Type Description
ts u64 Timestamp offset from epoch (seconds)
pid u16 Process ID
seq u32 Sequence number

Functions

Name Description
allocate::<L>(app) Allocate process ID from Redis
parse(id) Parse ID with default layout
parse_with::<L>(id) Parse ID with custom layout

ID Structure (Default Layout)

64-bit signed integer with second-precision timestamp:

┌───────┬──────────────────────────┬─────────────┬──────────────┐
│ 1 bit │        36 bits           │   11 bits   │   17 bits    │
│ sign  │    timestamp (sec)       │ process ID  │   sequence   │
│  (0)  │   (offset from epoch)    │  (0-2047)   │  (0-131071)  │
└───────┴──────────────────────────┴─────────────┴──────────────┘
  • Timestamp: 2^36 seconds ≈ 2177 years (2025-12-22 to ~4202)
  • Process ID: 2048 concurrent instances
  • Sequence: 131072 IDs per second per instance

Clock Drift Handling

When clock drifts backward:

  • Sequence borrowing continues from last timestamp
  • If drift exceeds 1 second, logs warning via tracing::warn
  • When sequence exhausted, timestamp advances automatically (borrows future time)

This ensures ID uniqueness even under NTP adjustments or VM migrations.

Process ID Allocation

Redis Key Format

sfid:{app}:{pid_le_bytes}

Heartbeat

  • Interval: 3 minutes
  • Expiration: 10 minutes
  • Auto-release on process exit (Drop trait)

Tech Stack

Crate Purpose
coarsetime Fast timestamp retrieval
fred Redis client
tokio Async runtime
uuid Unique identifier generation
thiserror Error handling
tracing Logging

About

This project is an open-source component of js0.site ⋅ Refactoring the Internet Plan.

We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:

sfid : 自动分配进程号的分布式雪花 ID 生成器

特性

  • 无锁原子 ID 生成
  • 可配置位布局（Layout trait）
  • 默认：36 位时间戳（秒）、11 位进程号、17 位序列号
  • 基于 Redis 自动分配进程号
  • 心跳机制，进程崩溃自动释放
  • 时钟回拨容错（序列号借用 + 告警日志）
  • 序列号耗尽处理（时间戳推进，借用未来时间）
  • 可配置纪元

安装

cargo add sfid

指定特性：

cargo add sfid -F snowflake,auto_pid,parse

快速开始

手动指定进程号

use sfid::{Snowflake, EPOCH};

let sf = Snowflake::new(EPOCH, 1);
let id = sf.next();
println!("{id}");

自动分配进程号 (Redis)

use sfid::{Snowflake, EPOCH};

#[tokio::main]
async fn main() -> sfid::Result<()> {
  let sf = Snowflake::auto("myapp", EPOCH).await?;
  let id = sf.next();
  println!("{id}");
  Ok(())
}

解析 ID

use sfid::parse;

let parsed = parse(id);
println!("ts: {}, pid: {}, seq: {}", parsed.ts, parsed.pid, parsed.seq);

自定义位布局

use sfid::{Layout, Snowflake, parse_with};

struct MyLayout;
impl Layout for MyLayout {
  const TS_BITS: u32 = 41;
  const PID_BITS: u32 = 10;
  const SEQ_BITS: u32 = 13;
}

let sf = Snowflake::<MyLayout>::new(my_epoch, 1);
let id = sf.next();
let parsed = parse_with::<MyLayout>(id);

API 参考

Traits

Layout

可配置的 ID 位布局。

常量 说明
TS_BITS 时间戳位数
PID_BITS 进程号位数
SEQ_BITS 序列号位数
SEQ_MASK 派生：(1 << SEQ_BITS) - 1
PID_MASK 派生：(1 << PID_BITS) - 1
TS_MASK 派生：(1 << TS_BITS) - 1
TS_SHIFT 派生：SEQ_BITS + PID_BITS
MAX_PID 派生：1 << PID_BITS

常量

名称 类型 说明
EPOCH u64 默认纪元：2025-12-22 00:00:00 UTC（秒）

结构体

Snowflake<L: Layout = DefaultLayout>

原子状态 ID 生成器。

方法 说明
new(epoch, pid) 手动指定进程号创建
auto(app, epoch) Redis 自动分配进程号创建
next() 生成下个 ID

DefaultLayout

默认位布局：36-11-17。

Pid

带心跳的进程号句柄，drop 时停止心跳。

方法 说明
id() 获取分配的进程号

ParsedId

解析后的 ID 组件。

字段 类型 说明
ts u64 相对纪元的时间戳偏移（秒）
pid u16 进程号
seq u32 序列号

函数

名称 说明
allocate::<L>(app) 从 Redis 分配进程号
parse(id) 使用默认布局解析 ID
parse_with::<L>(id) 使用自定义布局解析 ID

ID 结构（默认布局）

秒精度时间戳的 64 位有符号整数：

┌───────┬──────────────────────────┬─────────────┬──────────────┐
│ 1 bit │        36 bits           │   11 bits   │   17 bits    │
│ 符号  │      时间戳（秒）          │   进程号    │    序列号    │
│  (0)  │     (相对纪元偏移)        │  (0-2047)   │  (0-131071)  │
└───────┴──────────────────────────┴─────────────┴──────────────┘
  • 时间戳：2^36 秒 ≈ 2177 年（2025-12-22 到 ~4202 年）
  • 进程号：2048 并发实例
  • 序列号：每实例每秒 131072 ID

时钟回拨处理

当时钟回拨时：

  • 序列号借用，继续使用上次时间戳
  • 回拨超过 1 秒，通过 tracing::warn 记录告警
  • 序列号耗尽时，时间戳自动推进（借用未来时间）

确保 NTP 校时或虚拟机迁移时 ID 唯一性。

进程号分配

Redis 键格式

sfid:{app}:{pid_le_bytes}

心跳

  • 间隔：3 分钟
  • 过期：10 分钟
  • 进程退出自动释放 (Drop trait)

技术栈

Crate 用途
coarsetime 快速时间戳获取
fred Redis 客户端
tokio 异步运行时
uuid 唯一标识生成
thiserror 错误处理
tracing 日志

关于

本项目为 js0.site ⋅ 重构互联网计划 的开源组件。

我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：