Clawflake

Clawflake is a distributed ID number generation system inspired from Twitter's Snowflake.

The goal of Clawflake is to be hosted as a distributed system with all workers being isolated from each others apart from the machine ID.

Format

Unlike Snowflake, the composition of a Clawflake uses all 64 bits.

#	Name	Bits	Description
1	`time`	`45`	`The number of milliseconds passed from a configured epoch.`
2	`sequence`	`12`	`A sequence number rolling out whenever required.`
3	`machine`	`7`	`An identifier for the worker, between 0 and 127.`

Therefore, Clawflake ID numbers gives 2⁴⁵ - 1 = 1115.7 years of safety from the configured epoch. Thanks to the sequence number, a worker can handle 2¹² = 4069 generations per milliseconds at peak. The system can accept a maximum of 2⁷ = 128 machines for a given epoch.

Since Clawflake uses the most significant bit, converting a Clawflake ID from uint64 to int64 is not safe.

Usage

Before launching any worker, you need to determine the following information:

epoch: corresponds to the epoch workers will be using to generate IDs.
machine: the identifier for the machine.

Due to the format of a Clawflake, you can only have 128 workers (machine IDs between 0 and 127).

You can compile the worker by running

make generator

This will generate an executable named generator inside the bin directory.

You can then start the worker by running:


          export MACHINE_ID= # Worker ID, between 0 and 127
          export EPOCH= # Epoch to use in ID generation
          ./bin/generator -machine_id=$MACHINE_ID -epoch=$EPOCH -grpc_host=":5000"

TIP: Use the flag -help to view the documentation for the flags.

A worker should be running on port 5000. You can try generating some Clawflake ID numbers using the Generator API .

A test client is available in cmd/testclient/main.go.

License

Clawflake is governed by a BSD-style license that can be found in the LICENSE file.

Older codebase was licensed by the Apache License, Version 2.0, however none of the old code still exists.