357b2ee5f0
* Add v2 * Introduce staticcheck * Introduce golangci-lint * Add error checks * Add error checks * Lint v2 code * Improve CI trigger * Use io.ReadAll * Use int64 * Remove NewSonyflake * Fix errors * v2: Change MachineID, sequence, and AmazonEC2MachineID to int; update all usage and tests for type consistency * docs: update Settings struct in README to use int for MachineID and CheckMachineID (v2) * docs(v2): clarify Settings, StartTime, MachineID, and CheckMachineID comments and update README links and explanations * docs(v2/mock): improve comments and docstrings for mock implementations * docs(types): unify and clarify package and type docstrings for types.go in v1 and v2 * test(v2): refactor and modernize tests, improve error assertions, and update mocks for v2 * test(v2): normalize whitespace in pseudoSleep calls for consistency * feat(v2): add configurable TimeUnit and refactor time handling for So… (#67) * feat(v2): add configurable TimeUnit and refactor time handling for Sonyflake v2 * test(v2): add ToTime tests, clarify TimeUnit behavior, and update docs for v2 * gofmt
Sonyflake
Sonyflake is a distributed unique ID generator inspired by Twitter's Snowflake.
Sonyflake focuses on lifetime and performance on many host/core environment. So it has a different bit assignment from Snowflake. A Sonyflake ID is composed of
39 bits for time in units of 10 msec
8 bits for a sequence number
16 bits for a machine id
As a result, Sonyflake has the following advantages and disadvantages:
- The lifetime (174 years) is longer than that of Snowflake (69 years)
- It can work in more distributed machines (2^16) than Snowflake (2^10)
- It can generate 2^8 IDs per 10 msec at most in a single instance (fewer than Snowflake)
However, if you want more generation rate in a single host, you can easily run multiple Sonyflake instances parallelly using goroutines.
Installation
go get github.com/sony/sonyflake/v2
Usage
The function New creates a new Sonyflake instance.
func New(st Settings) (*Sonyflake, error)
You can configure Sonyflake by the struct Settings:
type Settings struct {
TimeUnit time.Duration
StartTime time.Time
MachineID func() (int, error)
CheckMachineID func(int) bool
}
-
TimeUnit is the time unit of Sonyflake. If TimeUnit is 0, the default time unit is used, which is 10 msec. TimeUnit must be equal to or greater than 1 msec.
-
StartTime is the time since which the Sonyflake time is defined as the elapsed time. If StartTime is 0, the start time of the Sonyflake instance is set to "2025-01-01 00:00:00 +0000 UTC". StartTime must be before the current time.
-
MachineID returns the unique ID of a Sonyflake instance. If MachineID returns an error, the instance will not be created. If MachineID is nil, the default MachineID is used, which returns the lower 16 bits of the private IP address.
-
CheckMachineID validates the uniqueness of a machine ID. If CheckMachineID returns false, the instance will not be created. If CheckMachineID is nil, no validation is done.
In order to get a new unique ID, you just have to call the method NextID.
func (sf *Sonyflake) NextID() (int64, error)
NextID can continue to generate IDs for about 174 years from StartTime by default. But after the Sonyflake time is over the limit, NextID returns an error.
AWS VPC and Docker
The awsutil package provides the function AmazonEC2MachineID that returns the lower 16-bit private IP address of the Amazon EC2 instance. It also works correctly on Docker by retrieving instance metadata.
AWS IPv4 VPC is usually assigned a single CIDR with a netmask between /28 and /16. So if each EC2 instance has a unique private IP address in AWS VPC, the lower 16 bits of the address is also unique. In this common case, you can use AmazonEC2MachineID as Settings.MachineID.
See example that runs Sonyflake on AWS Elastic Beanstalk.
License
The MIT License (MIT)
See LICENSE for details.