github.com/authzed/spicedb@v1.32.1-0.20240520085336-ebda56537386/internal/datastore/revisions/hlcrevision.go

package revisions

import (
	"fmt"
	"math"
	"strconv"
	"strings"
	"time"

	"github.com/shopspring/decimal"

	"github.com/authzed/spicedb/pkg/datastore"
	"github.com/authzed/spicedb/pkg/spiceerrors"
)

var zeroHLC = HLCRevision{}

// NOTE: This *must* match the length defined in CRDB or the implementation below will break.
const logicalClockLength = 10

var logicalClockOffset = uint32(math.Pow10(logicalClockLength + 1))

// HLCRevision is a revision that is a hybrid logical clock, stored as two integers.
// The first integer is the timestamp in nanoseconds, and the second integer is the
// logical clock defined as 11 digits, with the first digit being ignored to ensure
// precision of the given logical clock.
type HLCRevision struct {
	time         int64
	logicalclock uint32
}

// parseHLCRevisionString parses a string into a hybrid logical clock revision.
func parseHLCRevisionString(revisionStr string) (datastore.Revision, error) {
	pieces := strings.Split(revisionStr, ".")
	if len(pieces) == 1 {
		// If there is no decimal point, assume the revision is a timestamp.
		timestamp, err := strconv.ParseInt(pieces[0], 10, 64)
		if err != nil {
			return datastore.NoRevision, fmt.Errorf("invalid revision string: %q", revisionStr)
		}
		return HLCRevision{timestamp, 0}, nil
	}

	if len(pieces) != 2 {
		return datastore.NoRevision, fmt.Errorf("invalid revision string: %q", revisionStr)
	}

	timestamp, err := strconv.ParseInt(pieces[0], 10, 64)
	if err != nil {
		return datastore.NoRevision, fmt.Errorf("invalid revision string: %q", revisionStr)
	}

	if len(pieces[1]) > logicalClockLength {
		return datastore.NoRevision, spiceerrors.MustBugf("invalid revision string due to unexpected logical clock size (%d): %q", len(pieces[1]), revisionStr)
	}

	paddedLogicalClockStr := pieces[1] + strings.Repeat("0", logicalClockLength-len(pieces[1]))
	logicalclock, err := strconv.ParseInt(paddedLogicalClockStr, 10, 32)
	if err != nil {
		return datastore.NoRevision, fmt.Errorf("invalid revision string: %q", revisionStr)
	}

	return HLCRevision{timestamp, uint32(logicalclock) + logicalClockOffset}, nil
}

// HLCRevisionFromString parses a string into a hybrid logical clock revision.
func HLCRevisionFromString(revisionStr string) (HLCRevision, error) {
	rev, err := parseHLCRevisionString(revisionStr)
	if err != nil {
		return zeroHLC, err
	}

	return rev.(HLCRevision), nil
}

// NewForHLC creates a new revision for the given hybrid logical clock.
func NewForHLC(decimal decimal.Decimal) (HLCRevision, error) {
	rev, err := HLCRevisionFromString(decimal.String())
	if err != nil {
		return zeroHLC, fmt.Errorf("invalid HLC decimal: %v (%s) => %w", decimal, decimal.String(), err)
	}

	return rev, nil
}

// NewHLCForTime creates a new revision for the given time.
func NewHLCForTime(time time.Time) HLCRevision {
	return HLCRevision{time.UnixNano(), 0}
}

func (hlc HLCRevision) Equal(rhs datastore.Revision) bool {
	if rhs == datastore.NoRevision {
		rhs = zeroHLC
	}

	rhsHLC := rhs.(HLCRevision)
	return hlc.time == rhsHLC.time && hlc.logicalclock == rhsHLC.logicalclock
}

func (hlc HLCRevision) GreaterThan(rhs datastore.Revision) bool {
	if rhs == datastore.NoRevision {
		rhs = zeroHLC
	}

	rhsHLC := rhs.(HLCRevision)
	return hlc.time > rhsHLC.time || (hlc.time == rhsHLC.time && hlc.logicalclock > rhsHLC.logicalclock)
}

func (hlc HLCRevision) LessThan(rhs datastore.Revision) bool {
	if rhs == datastore.NoRevision {
		rhs = zeroHLC
	}

	rhsHLC := rhs.(HLCRevision)
	return hlc.time < rhsHLC.time || (hlc.time == rhsHLC.time && hlc.logicalclock < rhsHLC.logicalclock)
}

func (hlc HLCRevision) String() string {
	if hlc.logicalclock == 0 {
		return strconv.FormatInt(hlc.time, 10)
	}

	logicalClockString := strconv.FormatInt(int64(hlc.logicalclock)-int64(logicalClockOffset), 10)
	return strconv.FormatInt(hlc.time, 10) + "." + strings.Repeat("0", logicalClockLength-len(logicalClockString)) + logicalClockString
}

func (hlc HLCRevision) TimestampNanoSec() int64 {
	return hlc.time
}

func (hlc HLCRevision) InexactFloat64() float64 {
	if hlc.logicalclock == 0 {
		return float64(hlc.time)
	}

	return float64(hlc.time) + float64(hlc.logicalclock-logicalClockOffset)/math.Pow10(logicalClockLength)
}

func (hlc HLCRevision) ConstructForTimestamp(timestamp int64) WithTimestampRevision {
	return HLCRevision{timestamp, 0}
}

func (hlc HLCRevision) IntegerRepresentation() (int64, uint32) {
	return hlc.time, hlc.logicalclock
}

var (
	_ datastore.Revision    = HLCRevision{}
	_ WithTimestampRevision = HLCRevision{}
)

// HLCKeyFunc is used to convert a simple HLC for use in maps.
func HLCKeyFunc(r HLCRevision) HLCRevision {
	return r
}

// HLCKeyLessThanFunc is used to compare keys created by the HLCKeyFunc.
func HLCKeyLessThanFunc(lhs, rhs HLCRevision) bool {
	return lhs.time < rhs.time || (lhs.time == rhs.time && lhs.logicalclock < rhs.logicalclock)
}