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 ¶
- type Generator
- type ID
- func (id ID) Bytes() [20]byte
- func (id ID) Compare(other ID) int
- func (id ID) Inspect() identifier.Inspection
- func (id ID) IsZero() bool
- func (id ID) LogValue() slog.Value
- func (id ID) MarshalBinary() ([]byte, error)
- func (id ID) MarshalJSON() ([]byte, error)
- func (id ID) MarshalText() ([]byte, error)
- func (id *ID) Scan(src any) error
- func (id ID) String() string
- func (id *ID) UnmarshalBinary(data []byte) error
- func (id *ID) UnmarshalJSON(data []byte) error
- func (id *ID) UnmarshalText(text []byte) error
- func (id ID) Value() (driver.Value, error)
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 ¶
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 ¶
FromBytes copies any 20-byte representation as assigned, including all-zero bytes, which are distinct from the unassigned Go zero value.
func Parse ¶
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) Compare ¶
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) MarshalBinary ¶
MarshalBinary returns a new 20-byte representation, or identifier.ErrInvalid when unassigned.
func (ID) MarshalJSON ¶
MarshalJSON encodes canonical text or null when unassigned.
func (ID) MarshalText ¶
MarshalText returns newly allocated canonical text, or identifier.ErrInvalid when unassigned.
func (*ID) Scan ¶
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) UnmarshalBinary ¶
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 ¶
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 ¶
UnmarshalText parses text and replaces id only on success. Invalid input wraps identifier.ErrInvalid; input bytes are not retained.