Fix a missing link (#65)

* Allow IPv4 Link Local addresses (#50)

* Allow IPv4 Link Local addresses

Allow the use of link local addresses

* Update sonyflake.go

* Update sonyflake.go

* Update a comment

---------

Co-authored-by: Flavio Crisciani <f.crisciani@gmail.com>

.github/workflows/test.yml

@@ -0,0 +1,24 @@
+on: [push, pull_request]
+name: Test
+jobs:
+  test:
+    strategy:
+      matrix:
+        go-version: [1.23.x, 1.24.x]
+        os: [ubuntu-latest]
+    runs-on: ${{matrix.os}}
+    steps:
+    - name: Set up Go
+      uses: actions/setup-go@v2
+      with:
+        go-version: ${{matrix.go-version}}
+    - name: Checkout
+      uses: actions/checkout@v2
+    - name: gofmt
+      run: test -z "`gofmt -l .`"
+    - name: golint
+      run: test -z "`golint ./...`"
+    - name: go test
+      run: go test -v ./...
+    - name: Build example
+      run: cd example && ./linux64_build.sh

.travis.yml

@@ -1,14 +0,0 @@
-language: go
-go:
-  - 1.10.x
-  - 1.11.x
-sudo: false
-before_install:
-  - go get -u golang.org/x/lint/golint
-  - go get github.com/axw/gocov/gocov
-  - go get github.com/mattn/goveralls
-script:
-  - test -z "`gofmt -l .`"
-  - test -z "`golint ./...`"
-  - $GOPATH/bin/goveralls -service=travis-ci
-  - cd example && ./linux64_build.sh

README.md

@@ -2,17 +2,27 @@ Sonyflake
 =========
 
 [![GoDoc](https://godoc.org/github.com/sony/sonyflake?status.svg)](http://godoc.org/github.com/sony/sonyflake)
-[![Build Status](https://travis-ci.org/sony/sonyflake.svg?branch=master)](https://travis-ci.org/sony/sonyflake)
-[![Coverage Status](https://coveralls.io/repos/sony/sonyflake/badge.svg?branch=master&service=github)](https://coveralls.io/github/sony/sonyflake?branch=master)
 [![Go Report Card](https://goreportcard.com/badge/github.com/sony/sonyflake)](https://goreportcard.com/report/github.com/sony/sonyflake)
 
 Sonyflake is a distributed unique ID generator inspired by [Twitter's Snowflake](https://blog.twitter.com/2010/announcing-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 machine/thread (slower than Snowflake)
+
+However, if you want more generation rate in a single host,
+you can easily run multiple Sonyflake ID generators concurrently using goroutines.
+
 Installation
 ------------
 
@@ -23,10 +33,10 @@ go get github.com/sony/sonyflake
 Usage
 -----
 
-The function NewSonyflake creates a new Sonyflake instance.
+The function New creates a new Sonyflake instance.
 
 ```go
-func NewSonyflake(st Settings) *Sonyflake
+func New(st Settings) (*Sonyflake, error)
 ```
 
 You can configure Sonyflake by the struct Settings:
@@ -61,6 +71,10 @@ func (sf *Sonyflake) NextID() (uint64, error)
 NextID can continue to generate IDs for about 174 years from StartTime.
 But after the Sonyflake time is over the limit, NextID returns an error.
 
+> **Note:**
+> Sonyflake currently does not use the most significant bit of IDs,
+> so you can convert Sonyflake IDs from `uint64` to `int64` safely.
+
 AWS VPC and Docker
 ------------------
 
@@ -69,8 +83,8 @@ the function AmazonEC2MachineID that returns the lower 16-bit private IP address
 It also works correctly on Docker
 by retrieving [instance metadata](http://docs.aws.amazon.com/en_us/AWSEC2/latest/UserGuide/ec2-instance-metadata.html).
 
-[AWS VPC](http://docs.aws.amazon.com/en_us/AmazonVPC/latest/UserGuide/VPC_Subnets.html)
-is assigned a single CIDR with a netmask between /28 and /16.
+[AWS IPv4 VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-cidr-blocks.html)
+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.

go.mod

@@ -1,5 +1,3 @@
 module github.com/sony/sonyflake
 
-go 1.12
-
-require github.com/deckarep/golang-set v1.7.1
+go 1.13

go.sum

@@ -1,2 +0,0 @@
-github.com/deckarep/golang-set v1.7.1 h1:SCQV0S6gTtp6itiFrTqI+pfmJ4LN85S1YzhDf9rTHJQ=
-github.com/deckarep/golang-set v1.7.1/go.mod h1:93vsz/8Wt4joVM7c2AVqh+YRMiUSc14yDtF28KmMOgQ=

mock/sonyflake_mock.go

@@ -0,0 +1,35 @@
+// Package mock offers implementations of interfaces defined in types.go
+// This allows complete control over input / output for any given method that consumes
+// a given type
+package mock
+
+import (
+	"fmt"
+	"net"
+
+	"github.com/sony/sonyflake/types"
+)
+
+// NewSuccessfulInterfaceAddrs returns a single private IP address
+func NewSuccessfulInterfaceAddrs() types.InterfaceAddrs {
+	ifat := make([]net.Addr, 0, 1)
+	ifat = append(ifat, &net.IPNet{IP: []byte{192, 168, 0, 1}, Mask: []byte{255, 0, 0, 0}})
+
+	return func() ([]net.Addr, error) {
+		return ifat, nil
+	}
+}
+
+// NewFailingInterfaceAddrs returns an error
+func NewFailingInterfaceAddrs() types.InterfaceAddrs {
+	return func() ([]net.Addr, error) {
+		return nil, fmt.Errorf("test error")
+	}
+}
+
+// NewFailingInterfaceAddrs returns an empty slice of addresses
+func NewNilInterfaceAddrs() types.InterfaceAddrs {
+	return func() ([]net.Addr, error) {
+		return []net.Addr{}, nil
+	}
+}

sonyflake.go

@@ -1,9 +1,10 @@
 // Package sonyflake implements Sonyflake, a distributed unique ID generator inspired by Twitter's 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
+//
+//	39 bits for time in units of 10 msec
+//	 8 bits for a sequence number
+//	16 bits for a machine id
 package sonyflake
 
 import (
@@ -11,6 +12,8 @@ import (
 	"net"
 	"sync"
 	"time"
+
+	"github.com/sony/sonyflake/types"
 )
 
 // These constants are the bit lengths of Sonyflake ID parts.
@@ -49,19 +52,29 @@ type Sonyflake struct {
 	machineID   uint16
 }
 
-// NewSonyflake returns a new Sonyflake configured with the given Settings.
-// NewSonyflake returns nil in the following cases:
+var (
+	ErrStartTimeAhead   = errors.New("start time is ahead of now")
+	ErrNoPrivateAddress = errors.New("no private ip address")
+	ErrOverTimeLimit    = errors.New("over the time limit")
+	ErrInvalidMachineID = errors.New("invalid machine id")
+)
+
+var defaultInterfaceAddrs = net.InterfaceAddrs
+
+// New returns a new Sonyflake configured with the given Settings.
+// New returns an error in the following cases:
 // - Settings.StartTime is ahead of the current time.
 // - Settings.MachineID returns an error.
 // - Settings.CheckMachineID returns false.
-func NewSonyflake(st Settings) *Sonyflake {
+func New(st Settings) (*Sonyflake, error) {
+	if st.StartTime.After(time.Now()) {
+		return nil, ErrStartTimeAhead
+	}
+
 	sf := new(Sonyflake)
 	sf.mutex = new(sync.Mutex)
 	sf.sequence = uint16(1<<BitLenSequence - 1)
 
-	if st.StartTime.After(time.Now()) {
-		return nil
-	}
 	if st.StartTime.IsZero() {
 		sf.startTime = toSonyflakeTime(time.Date(2014, 9, 1, 0, 0, 0, 0, time.UTC))
 	} else {
@@ -70,14 +83,28 @@ func NewSonyflake(st Settings) *Sonyflake {
 
 	var err error
 	if st.MachineID == nil {
-		sf.machineID, err = lower16BitPrivateIP()
+		sf.machineID, err = lower16BitPrivateIP(defaultInterfaceAddrs)
 	} else {
 		sf.machineID, err = st.MachineID()
 	}
-	if err != nil || (st.CheckMachineID != nil && !st.CheckMachineID(sf.machineID)) {
-		return nil
+	if err != nil {
+		return nil, err
 	}
 
+	if st.CheckMachineID != nil && !st.CheckMachineID(sf.machineID) {
+		return nil, ErrInvalidMachineID
+	}
+
+	return sf, nil
+}
+
+// NewSonyflake returns a new Sonyflake configured with the given Settings.
+// NewSonyflake returns nil in the following cases:
+// - Settings.StartTime is ahead of the current time.
+// - Settings.MachineID returns an error.
+// - Settings.CheckMachineID returns false.
+func NewSonyflake(st Settings) *Sonyflake {
+	sf, _ := New(st)
 	return sf
 }
 
@@ -116,13 +143,13 @@ func currentElapsedTime(startTime int64) int64 {
 }
 
 func sleepTime(overtime int64) time.Duration {
-	return time.Duration(overtime)*10*time.Millisecond -
-		time.Duration(time.Now().UTC().UnixNano()%sonyflakeTimeUnit)*time.Nanosecond
+	return time.Duration(overtime*sonyflakeTimeUnit) -
+		time.Duration(time.Now().UTC().UnixNano()%sonyflakeTimeUnit)
 }
 
 func (sf *Sonyflake) toID() (uint64, error) {
 	if sf.elapsedTime >= 1<<BitLenTime {
-		return 0, errors.New("over the time limit")
+		return 0, ErrOverTimeLimit
 	}
 
 	return uint64(sf.elapsedTime)<<(BitLenSequence+BitLenMachineID) |
@@ -130,8 +157,8 @@ func (sf *Sonyflake) toID() (uint64, error) {
 		uint64(sf.machineID), nil
 }
 
-func privateIPv4() (net.IP, error) {
-	as, err := net.InterfaceAddrs()
+func privateIPv4(interfaceAddrs types.InterfaceAddrs) (net.IP, error) {
+	as, err := interfaceAddrs()
 	if err != nil {
 		return nil, err
 	}
@@ -147,16 +174,17 @@ func privateIPv4() (net.IP, error) {
 			return ip, nil
 		}
 	}
-	return nil, errors.New("no private ip address")
+	return nil, ErrNoPrivateAddress
 }
 
 func isPrivateIPv4(ip net.IP) bool {
+	// Allow private IP addresses (RFC1918) and link-local addresses (RFC3927)
 	return ip != nil &&
-		(ip[0] == 10 || ip[0] == 172 && (ip[1] >= 16 && ip[1] < 32) || ip[0] == 192 && ip[1] == 168)
+		(ip[0] == 10 || ip[0] == 172 && (ip[1] >= 16 && ip[1] < 32) || ip[0] == 192 && ip[1] == 168 || ip[0] == 169 && ip[1] == 254)
 }
 
-func lower16BitPrivateIP() (uint16, error) {
-	ip, err := privateIPv4()
+func lower16BitPrivateIP(interfaceAddrs types.InterfaceAddrs) (uint16, error) {
+	ip, err := privateIPv4(interfaceAddrs)
 	if err != nil {
 		return 0, err
 	}
@@ -164,15 +192,33 @@ func lower16BitPrivateIP() (uint16, error) {
 	return uint16(ip[2])<<8 + uint16(ip[3]), nil
 }
 
+// ElapsedTime returns the elapsed time when the given Sonyflake ID was generated.
+func ElapsedTime(id uint64) time.Duration {
+	return time.Duration(elapsedTime(id) * sonyflakeTimeUnit)
+}
+
+func elapsedTime(id uint64) uint64 {
+	return id >> (BitLenSequence + BitLenMachineID)
+}
+
+// SequenceNumber returns the sequence number of a Sonyflake ID.
+func SequenceNumber(id uint64) uint64 {
+	const maskSequence = uint64((1<<BitLenSequence - 1) << BitLenMachineID)
+	return id & maskSequence >> BitLenMachineID
+}
+
+// MachineID returns the machine ID of a Sonyflake ID.
+func MachineID(id uint64) uint64 {
+	const maskMachineID = uint64(1<<BitLenMachineID - 1)
+	return id & maskMachineID
+}
+
 // Decompose returns a set of Sonyflake ID parts.
 func Decompose(id uint64) map[string]uint64 {
-	const maskSequence = uint64((1<<BitLenSequence - 1) << BitLenMachineID)
-	const maskMachineID = uint64(1<<BitLenMachineID - 1)
-
 	msb := id >> 63
-	time := id >> (BitLenSequence + BitLenMachineID)
-	sequence := id & maskSequence >> BitLenMachineID
-	machineID := id & maskMachineID
+	time := elapsedTime(id)
+	sequence := SequenceNumber(id)
+	machineID := MachineID(id)
 	return map[string]uint64{
 		"id":         id,
 		"msb":        msb,

sonyflake_test.go

@@ -1,12 +1,15 @@
 package sonyflake
 
 import (
+	"errors"
 	"fmt"
+	"net"
 	"runtime"
 	"testing"
 	"time"
 
-	"github.com/deckarep/golang-set"
+	"github.com/sony/sonyflake/mock"
+	"github.com/sony/sonyflake/types"
 )
 
 var sf *Sonyflake
@@ -25,7 +28,7 @@ func init() {
 
 	startTime = toSonyflakeTime(st.StartTime)
 
-	ip, _ := lower16BitPrivateIP()
+	ip, _ := lower16BitPrivateIP(defaultInterfaceAddrs)
 	machineID = uint64(ip)
 }
 
@@ -37,35 +40,83 @@ func nextID(t *testing.T) uint64 {
 	return id
 }
 
-func TestSonyflakeOnce(t *testing.T) {
-	sleepTime := uint64(50)
-	time.Sleep(time.Duration(sleepTime) * 10 * time.Millisecond)
+func TestNew(t *testing.T) {
+	genError := fmt.Errorf("an error occurred while generating ID")
 
-	id := nextID(t)
-	parts := Decompose(id)
-
-	actualMSB := parts["msb"]
-	if actualMSB != 0 {
-		t.Errorf("unexpected msb: %d", actualMSB)
+	tests := []struct {
+		name     string
+		settings Settings
+		err      error
+	}{
+		{
+			name: "failure: time ahead",
+			settings: Settings{
+				StartTime: time.Now().Add(time.Minute),
+			},
+			err: ErrStartTimeAhead,
+		},
+		{
+			name: "failure: machine ID",
+			settings: Settings{
+				MachineID: func() (uint16, error) {
+					return 0, genError
+				},
+			},
+			err: genError,
+		},
+		{
+			name: "failure: invalid machine ID",
+			settings: Settings{
+				CheckMachineID: func(uint16) bool {
+					return false
+				},
+			},
+			err: ErrInvalidMachineID,
+		},
+		{
+			name:     "success",
+			settings: Settings{},
+		},
 	}
 
-	actualTime := parts["time"]
-	if actualTime < sleepTime || actualTime > sleepTime+1 {
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			sonyflake, err := New(test.settings)
+
+			if !errors.Is(err, test.err) {
+				t.Fatalf("unexpected value, want %#v, got %#v", test.err, err)
+			}
+
+			if sonyflake == nil && err == nil {
+				t.Fatal("unexpected value, sonyflake should not be nil")
+			}
+		})
+	}
+}
+
+func TestSonyflakeOnce(t *testing.T) {
+	sleepTime := time.Duration(50 * sonyflakeTimeUnit)
+	time.Sleep(sleepTime)
+
+	id := nextID(t)
+
+	actualTime := ElapsedTime(id)
+	if actualTime < sleepTime || actualTime > sleepTime+sonyflakeTimeUnit {
 		t.Errorf("unexpected time: %d", actualTime)
 	}
 
-	actualSequence := parts["sequence"]
+	actualSequence := SequenceNumber(id)
 	if actualSequence != 0 {
 		t.Errorf("unexpected sequence: %d", actualSequence)
 	}
 
-	actualMachineID := parts["machine-id"]
+	actualMachineID := MachineID(id)
 	if actualMachineID != machineID {
 		t.Errorf("unexpected machine id: %d", actualMachineID)
 	}
 
 	fmt.Println("sonyflake id:", id)
-	fmt.Println("decompose:", parts)
+	fmt.Println("decompose:", Decompose(id))
 }
 
 func currentTime() int64 {
@@ -84,9 +135,12 @@ func TestSonyflakeFor10Sec(t *testing.T) {
 		parts := Decompose(id)
 		numID++
 
-		if id <= lastID {
+		if id == lastID {
 			t.Fatal("duplicated id")
 		}
+		if id < lastID {
+			t.Fatal("must increase with time")
+		}
 		lastID = id
 
 		current = currentTime()
@@ -139,40 +193,15 @@ func TestSonyflakeInParallel(t *testing.T) {
 		go generate()
 	}
 
-	set := mapset.NewSet()
+	set := make(map[uint64]struct{})
 	for i := 0; i < numID*numGenerator; i++ {
 		id := <-consumer
-		if set.Contains(id) {
+		if _, ok := set[id]; ok {
 			t.Fatal("duplicated id")
-		} else {
-			set.Add(id)
 		}
+		set[id] = struct{}{}
 	}
-	fmt.Println("number of id:", set.Cardinality())
-}
-
-func TestNilSonyflake(t *testing.T) {
-	var startInFuture Settings
-	startInFuture.StartTime = time.Now().Add(time.Duration(1) * time.Minute)
-	if NewSonyflake(startInFuture) != nil {
-		t.Errorf("sonyflake starting in the future")
-	}
-
-	var noMachineID Settings
-	noMachineID.MachineID = func() (uint16, error) {
-		return 0, fmt.Errorf("no machine id")
-	}
-	if NewSonyflake(noMachineID) != nil {
-		t.Errorf("sonyflake with no machine id")
-	}
-
-	var invalidMachineID Settings
-	invalidMachineID.CheckMachineID = func(uint16) bool {
-		return false
-	}
-	if NewSonyflake(invalidMachineID) != nil {
-		t.Errorf("sonyflake with invalid machine id")
-	}
+	fmt.Println("number of id:", len(set))
 }
 
 func pseudoSleep(period time.Duration) {
@@ -190,3 +219,96 @@ func TestNextIDError(t *testing.T) {
 		t.Errorf("time is not over")
 	}
 }
+
+func TestPrivateIPv4(t *testing.T) {
+	testCases := []struct {
+		description    string
+		expected       net.IP
+		interfaceAddrs types.InterfaceAddrs
+		error          string
+	}{
+		{
+			description:    "InterfaceAddrs returns an error",
+			expected:       nil,
+			interfaceAddrs: mock.NewFailingInterfaceAddrs(),
+			error:          "test error",
+		},
+		{
+			description:    "InterfaceAddrs returns an empty or nil list",
+			expected:       nil,
+			interfaceAddrs: mock.NewNilInterfaceAddrs(),
+			error:          "no private ip address",
+		},
+		{
+			description:    "InterfaceAddrs returns one or more IPs",
+			expected:       net.IP{192, 168, 0, 1},
+			interfaceAddrs: mock.NewSuccessfulInterfaceAddrs(),
+			error:          "",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.description, func(t *testing.T) {
+			actual, err := privateIPv4(tc.interfaceAddrs)
+
+			if (err != nil) && (tc.error == "") {
+				t.Errorf("expected no error, but got: %s", err)
+				return
+			} else if (err != nil) && (tc.error != "") {
+				return
+			}
+
+			if net.IP.Equal(actual, tc.expected) {
+				return
+			} else {
+				t.Errorf("error: expected: %s, but got: %s", tc.expected, actual)
+			}
+		})
+	}
+}
+
+func TestLower16BitPrivateIP(t *testing.T) {
+	testCases := []struct {
+		description    string
+		expected       uint16
+		interfaceAddrs types.InterfaceAddrs
+		error          string
+	}{
+		{
+			description:    "InterfaceAddrs returns an empty or nil list",
+			expected:       0,
+			interfaceAddrs: mock.NewNilInterfaceAddrs(),
+			error:          "no private ip address",
+		},
+		{
+			description:    "InterfaceAddrs returns one or more IPs",
+			expected:       1,
+			interfaceAddrs: mock.NewSuccessfulInterfaceAddrs(),
+			error:          "",
+		},
+	}
+	for _, tc := range testCases {
+		t.Run(tc.description, func(t *testing.T) {
+			actual, err := lower16BitPrivateIP(tc.interfaceAddrs)
+
+			if (err != nil) && (tc.error == "") {
+				t.Errorf("expected no error, but got: %s", err)
+				return
+			} else if (err != nil) && (tc.error != "") {
+				return
+			}
+
+			if actual == tc.expected {
+				return
+			} else {
+				t.Errorf("error: expected: %v, but got: %v", tc.expected, actual)
+			}
+		})
+	}
+}
+
+func TestSonyflakeTimeUnit(t *testing.T) {
+	if time.Duration(sonyflakeTimeUnit) != 10*time.Millisecond {
+		t.Errorf("unexpected time unit")
+	}
+}

types/types.go

@@ -0,0 +1,8 @@
+// Package Types defines type signatures used throughout SonyFlake. This allows for
+// fine-tuned control over imports, and the ability to mock out imports as well
+package types
+
+import "net"
+
+// InterfaceAddrs defines the interface used for retrieving network addresses
+type InterfaceAddrs func() ([]net.Addr, error)