ksuid

package
v2.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package ksuid implements the pinned Segment KSUID format at revision d33724947fcfba7949906c2b1821e96a1c8d06e7: 20-byte values and 27-byte Base62 text. Start with Parse or NewGenerator. The package requires no service or cgo and starts no background work.

Generation is monotonic within one instance, unlike independent-random Segment generation. It reveals seconds and local issuance order, not global ordering or authorization. IDENTIFIER-KSUID-DEC-001 in docs/specification-decisions.md records this wire-compatible policy.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Generator

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

Generator serializes New calls and owns a monotonic sequence. Within a second, it increments the initial random payload; this leaks local issuance order and differs from independent-random KSUID generation while preserving wire interoperability. Construct it with NewGenerator; its zero value is not ready for use and it must not be copied after first use. Clock/entropy are borrowed, never closed, and called under the lock. They must not reenter the generator and need their own synchronization if shared elsewhere.

func NewGenerator

func NewGenerator(clock identifier.Clock, entropy io.Reader) *Generator

NewGenerator creates a monotonic KSUID generator. Nil inputs select a system clock and crypto/rand.Reader for this generator instance.

func (*Generator) New

func (generator *Generator) New() (ID, error)

New draws fresh 128-bit payload entropy on a new second and increments it within that second. Failure returns a zero ID: identifier.ErrInvalid for time outside Unix seconds [1400000000, 1400000000+2^32-1], ErrClockRollback for rollback, ErrOverflow for payload exhaustion, and ErrEntropy for reader errors. Failed calls preserve committed state but may consume entropy. Clock/reader calls can block without cancellation; ordering and uniqueness are not global.

type ID

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

ID is an immutable KSUID. A validity bit distinguishes an unassigned value from the valid all-zero KSUID. Read-only methods may run concurrently. Decode methods require a non-nil receiver and exclusive access; they leave it unchanged on invalid input.

func FromBytes

func FromBytes(value [20]byte) ID

FromBytes copies any 20-byte representation as assigned, including all-zero bytes, which are distinct from the unassigned Go zero value.

func Parse

func Parse(text string) (ID, error)

Parse accepts exactly the canonical 27-character Base62 representation. Failure returns the zero ID with identifier.ErrInvalid. Re-encoding checks the pinned Segment format's canonical representation (IDENTIFIER-KSUID-DEC-001; TestReferenceVectorAndDifferentialParsing).

func (ID) Bytes

func (id ID) Bytes() [20]byte

Bytes returns a copy of the KSUID representation.

func (ID) Compare

func (id ID) Compare(other ID) int

Compare returns -1, 0, or 1 according to binary ordering, ignoring assignment. An unassigned value compares equal to the assigned all-zero KSUID.

func (ID) Inspect

func (id ID) Inspect() identifier.Inspection

Inspect returns the second-resolution timestamp exposed by a KSUID.

func (ID) IsZero

func (id ID) IsZero() bool

IsZero reports whether no KSUID has been assigned.

func (ID) LogValue

func (id ID) LogValue() slog.Value

LogValue redacts the KSUID from structured logs.

func (ID) MarshalBinary

func (id ID) MarshalBinary() ([]byte, error)

MarshalBinary returns a new 20-byte representation, or identifier.ErrInvalid when unassigned.

func (ID) MarshalJSON

func (id ID) MarshalJSON() ([]byte, error)

MarshalJSON encodes canonical text or null when unassigned.

func (ID) MarshalText

func (id ID) MarshalText() ([]byte, error)

MarshalText returns newly allocated canonical text, or identifier.ErrInvalid when unassigned.

func (*ID) Scan

func (id *ID) Scan(src any) error

Scan accepts canonical strings, byte slices, or nil (SQL NULL). A 20-byte slice is interpreted as binary; other slices are text. Invalid input wraps identifier.ErrInvalid and leaves id unchanged; nil clears id. Bytes are copied.

func (ID) String

func (id ID) String() string

String returns canonical Base62 text, or empty text when unassigned.

func (*ID) UnmarshalBinary

func (id *ID) UnmarshalBinary(data []byte) error

UnmarshalBinary requires exactly 20 bytes and copies them on success. Invalid input wraps identifier.ErrInvalid and leaves id unchanged. Every bit pattern, including all-zero bytes, is an assigned value.

func (*ID) UnmarshalJSON

func (id *ID) UnmarshalJSON(data []byte) error

UnmarshalJSON parses a bounded JSON string, or clears id for the exact token null. Invalid input wraps identifier.ErrInvalid and leaves id unchanged. Encoded input is limited to 164 bytes, including quotes and escapes.

func (*ID) UnmarshalText

func (id *ID) UnmarshalText(text []byte) error

UnmarshalText parses text and replaces id only on success. Invalid input wraps identifier.ErrInvalid; input bytes are not retained.

func (ID) Value

func (id ID) Value() (driver.Value, error)

Value returns canonical text for database/sql, or nil (SQL NULL) when unassigned.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址