orbitid

README

Orbit ID for Go

Go implementation of the Orbit ID v1 unsigned 64-bit format.

Source of truth lives in the monorepo under packages/go. Published module path is the orbit-id/go mirror (same pattern as Packagist / orbit-id/php).

Install

go get github.com/orbit-id/go@v1.1.0

Import as package orbitid:

import (
    "fmt"

    orbitid "github.com/orbit-id/go"
)

func main() {
    generator, err := orbitid.NewGenerator(orbitid.GeneratorOptions{Node: 7})
    if err != nil {
        panic(err)
    }
    id, err := generator.Generate(1)
    if err != nil {
        panic(err)
    }
    fmt.Println(orbitid.ToDecimalString(id))
}

Version tags

On each monorepo vX.Y.Z release, CI mirrors packages/go to orbit-id/go and pushes the same tag there. Consumers use that mirror tag via proxy.golang.org.

See Cross-registry versioning and Go module publishing.

API notes

Use Encode / Decode for fields, Parse for a uint64 or canonical decimal string, and IsValid for syntactic validation only. Decimal strings must be unsigned and canonical (no signs, whitespace, or leading zeroes).

Test

go test ./...

Documentation

Overview

Package orbitid implements the Orbit ID v1 unsigned 64-bit format.

Index

• Constants
• func Encode(fields Fields) (uint64, error)
• func FromDecimalString(input string) (uint64, error)
• func FromUnixTimeMs(unixMs int64) int64
• func GetNode(id any) (int, error)
• func GetSequence(id any) (int, error)
• func GetTimestamp(id any) (uint64, error)
• func GetType(id any) (int, error)
• func IsValid(id any) bool
• func ToDecimalString(id uint64) string
• func ToHexString(id uint64) string
• func ToUnixTimeMs(timestamp uint64) uint64
• type Clock
  • func SystemClock() Clock
• type DecisionAction
• type Error
  • func (e *Error) Error() string
• type ErrorCode
• type Fields
  • func Decode(id uint64) Fields
  • func Parse(id any) (Fields, error)
• type GenerateDecision
• type Generator
  • func NewGenerator(options GeneratorOptions) (*Generator, error)
  • func (g *Generator) Decide(typ int, nowTimestamp ...int64) GenerateDecision
  • func (g *Generator) Generate(typ int) (uint64, error)
  • func (g *Generator) GetLastTimestamp() uint64
  • func (g *Generator) GetSequence() int
  • func (g *Generator) Node() int
  • func (g *Generator) RestoreState(lastTimestamp uint64, sequence int) error
• type GeneratorOptions
• type SequenceExhaustedMode

Constants

const (
	OrbitEpochUnixMs                int64  = 1767225600000
	TimestampBits                          = 41
	TypeBits                               = 6
	NodeBits                               = 7
	SequenceBits                           = 10
	TimestampShift                         = 23
	TypeShift                              = 17
	NodeShift                              = 10
	MaxTimestamp                    uint64 = (1 << TimestampBits) - 1
	MaxType                         int    = (1 << TypeBits) - 1
	MaxNode                         int    = (1 << NodeBits) - 1
	MaxSequence                     int    = (1 << SequenceBits) - 1
	DefaultClockRollbackToleranceMs int64  = 5000
)

Functions

func Encode

func Encode(fields Fields) (uint64, error)

Encode validates fields and packs them into an unsigned 64-bit Orbit ID.

func FromDecimalString

func FromDecimalString(input string) (uint64, error)

FromDecimalString accepts only canonical, unsigned base-10 uint64 strings.

func FromUnixTimeMs

func FromUnixTimeMs(unixMs int64) int64

FromUnixTimeMs converts Unix milliseconds to an Orbit timestamp. A negative result is invalid for encoding and will be rejected by Generator/Encode.

func GetNode

func GetNode(id any) (int, error)

func GetSequence

func GetSequence(id any) (int, error)

func GetTimestamp

func GetTimestamp(id any) (uint64, error)

GetTimestamp returns milliseconds since Orbit Epoch.

func GetType

func GetType(id any) (int, error)

func IsValid

func IsValid(id any) bool

IsValid reports syntactic validity only; it does not prove an ID was issued.

func ToDecimalString

func ToDecimalString(id uint64) string

func ToHexString

func ToHexString(id uint64) string

func ToUnixTimeMs

func ToUnixTimeMs(timestamp uint64) uint64

Types

type Clock

type Clock interface {
	CurrentOrbitTimestampMs() int64
}

Clock supplies milliseconds since Orbit Epoch. It is injectable for tests.

func SystemClock

func SystemClock() Clock

SystemClock returns the production wall-clock Orbit timestamp source.

type DecisionAction

type DecisionAction string

const (
	DecisionIssue      DecisionAction = "issue"
	DecisionWait       DecisionAction = "wait"
	DecisionWaitNextMs DecisionAction = "wait_next_ms"
	DecisionError      DecisionAction = "error"
)

type Error

type Error struct {
	Code    ErrorCode
	Message string
}

Error is returned for invalid Orbit input or failed generation.

func (*Error) Error

func (e *Error) Error() string

type ErrorCode

type ErrorCode string

ErrorCode is a stable, machine-readable Orbit error code.

const (
	InvalidType       ErrorCode = "INVALID_TYPE"
	InvalidNode       ErrorCode = "INVALID_NODE"
	InvalidSequence   ErrorCode = "INVALID_SEQUENCE"
	InvalidTimestamp  ErrorCode = "INVALID_TIMESTAMP"
	InvalidDecimal    ErrorCode = "INVALID_DECIMAL"
	ClockRollback     ErrorCode = "CLOCK_ROLLBACK"
	SequenceExhausted ErrorCode = "SEQUENCE_EXHAUSTED"
	NodeOwnershipLost ErrorCode = "NODE_OWNERSHIP_LOST"
)

type Fields

type Fields struct {
	Timestamp uint64
	Type      int
	Node      int
	Sequence  int
}

Fields are the decoded Orbit ID fields. Timestamp is milliseconds since OrbitEpochUnixMs.

func Decode

func Decode(id uint64) Fields

Decode unpacks an unsigned 64-bit Orbit ID.

func Parse

func Parse(id any) (Fields, error)

Parse accepts a uint64 Orbit ID or canonical decimal string and decodes it.

type GenerateDecision

type GenerateDecision struct {
	Action             DecisionAction
	Timestamp          uint64
	Sequence           int
	WaitUntilTimestamp uint64
	FromTimestamp      uint64
	Error              ErrorCode
}

GenerateDecision describes the next safe generator action.

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator issues Orbit IDs for one exclusively assigned node.

func NewGenerator

func NewGenerator(options GeneratorOptions) (*Generator, error)

func (*Generator) Decide

func (g *Generator) Decide(typ int, nowTimestamp ...int64) GenerateDecision

Decide evaluates a generation request without changing state.

func (*Generator) Generate

func (g *Generator) Generate(typ int) (uint64, error)

Generate serializes state changes and returns a newly issued ID. Type 0 is reserved and is rejected.

func (*Generator) GetLastTimestamp

func (g *Generator) GetLastTimestamp() uint64

func (*Generator) GetSequence

func (g *Generator) GetSequence() int

func (*Generator) Node

func (g *Generator) Node() int

func (*Generator) RestoreState

func (g *Generator) RestoreState(lastTimestamp uint64, sequence int) error

RestoreState seeds persisted generator state for restart recovery or tests.

type GeneratorOptions

type GeneratorOptions struct {
	Node                     int
	Clock                    Clock
	ClockRollbackToleranceMs int64
	OnSequenceExhausted      SequenceExhaustedMode
	// ConfirmOwnership may fail closed when a node lease is lost.
	ConfirmOwnership func() bool
}

type SequenceExhaustedMode

type SequenceExhaustedMode string

const (
	SequenceExhaustedWait SequenceExhaustedMode = "wait"
	SequenceExhaustedFail SequenceExhaustedMode = "fail"
)