Documentation
¶
Overview ¶
Package id provides the CheckpointID type for identifying checkpoints. This is a separate package to avoid import cycles between paths, trailers, and checkpoint.
Index ¶
- Constants
- func Validate(s string) error
- type CheckpointID
- func (id CheckpointID) DisplayShort() string
- func (id CheckpointID) IsEmpty() bool
- func (id CheckpointID) Kind() Kind
- func (id CheckpointID) MarshalJSON() ([]byte, error)
- func (id CheckpointID) Path() string
- func (id CheckpointID) ShardFor() string
- func (id CheckpointID) String() string
- func (id *CheckpointID) UnmarshalJSON(data []byte) error
- type Kind
Constants ¶
const CheckpointPattern = `(?:` + Pattern + `|` + ulidPattern + `)`
CheckpointPattern matches a checkpoint ID in free text in either format (legacy 12-hex or ULID). Use this — not Pattern — when scanning text such as the Entire-Checkpoint commit trailer for a candidate checkpoint ID, then validate the captured token via NewCheckpointID/Validate (CheckpointPattern is a loose shape, not authoritative validation).
const MaxIDLength = ulid.EncodedSize
MaxIDLength is the longest a valid checkpoint ID can be — a 26-character ULID. Use it (not ShortIDLength) when reasoning about whether a string could be a checkpoint ID or a prefix of one, since IDs are no longer fixed-width. Tied to oklog/ulid's own encoded-size constant so the three ULID-width sites (this, ulidPattern's {26}, and the library) cannot drift apart.
const Pattern = `[0-9a-f]{12}`
Pattern is the regex pattern for a legacy checkpoint ID: exactly 12 lowercase hex characters. Exported for use in other packages (e.g., trailers) to avoid pattern duplication. It is also reused by investigate/provenance for *run IDs*, which are always 12-hex — do NOT widen this to include ULIDs; use CheckpointPattern for matching a checkpoint ID that may be either format.
const ShortIDLength = 12
ShortIDLength is the standard length for truncating IDs for display purposes. Used for tool use IDs, session IDs, and commit hashes in logs and messages.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CheckpointID ¶
type CheckpointID string
CheckpointID identifies a checkpoint. It comes in two formats: a legacy 12-character lowercase hex ID and a 26-character Crockford base32 ULID (see Kind / CheckpointPattern). It links code commits to their checkpoint metadata.
const EmptyCheckpointID CheckpointID = ""
EmptyCheckpointID represents an unset or invalid checkpoint ID.
func Generate ¶
func Generate() (CheckpointID, error)
Generate creates a new random 12-character hex checkpoint ID.
Generation stays 12-hex regardless of storage backend. Emitting ULIDs is a separate, store-coupled change (new checkpoints get a ULID only under the git-refs store); this package only recognizes/validates both formats.
func GenerateULID ¶ added in v0.8.0
func GenerateULID() (CheckpointID, error)
GenerateULID creates a new 26-character Crockford base32 ULID checkpoint ID: a millisecond timestamp prefix plus crypto-random entropy, so IDs are unique and lexicographically time-sortable. It is the format the git-refs store uses (chosen by checkpoint.GenerateCheckpointID); the value is canonical and passes KindOf/Validate as KindULID.
The timestamp is Unix epoch milliseconds (via ulid.Now), so it is inherently timezone-independent — the machine's local zone does not affect the ID.
func MustCheckpointID ¶
func MustCheckpointID(s string) CheckpointID
MustCheckpointID creates a CheckpointID from a string, panicking if invalid. Use only when the ID is known to be valid (e.g., from trusted sources).
func NewCheckpointID ¶
func NewCheckpointID(s string) (CheckpointID, error)
NewCheckpointID creates a CheckpointID from a string, validating its format. Returns an error unless the string is a valid checkpoint ID (12-char hex or ULID).
func (CheckpointID) DisplayShort ¶ added in v0.8.0
func (id CheckpointID) DisplayShort() string
DisplayShort returns the checkpoint ID trimmed for compact display. A legacy hex ID is random throughout, so its ShortIDLength-char prefix identifies it and resolves as a prefix. A ULID encodes a millisecond timestamp in its leading characters (near-identical for checkpoints minted close in time) with entropy only in the tail, so a front-truncated ULID is both ambiguous and misleading — it looks like a complete ID but won't resolve — so a ULID is returned in full. Non-ID strings (e.g. "temporary") are trimmed like the legacy case.
func (CheckpointID) IsEmpty ¶
func (id CheckpointID) IsEmpty() bool
IsEmpty returns true if the checkpoint ID is empty or unset.
func (CheckpointID) Kind ¶ added in v0.8.0
func (id CheckpointID) Kind() Kind
Kind classifies this checkpoint ID.
func (CheckpointID) MarshalJSON ¶
func (id CheckpointID) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler.
func (CheckpointID) Path ¶
func (id CheckpointID) Path() string
Path returns the sharded path for this checkpoint ID on entire/checkpoints/v1. Uses first 2 characters as shard (256 buckets), remaining as folder name. Example: "a3b2c4d5e6f7" -> "a3/b2c4d5e6f7"
func (CheckpointID) ShardFor ¶ added in v0.8.0
func (id CheckpointID) ShardFor() string
ShardFor returns the two-character shard for storing this ID under a per-checkpoint git ref (refs/entire/checkpoints/<shard>/<id>): the LAST two characters of the ID, for BOTH supported formats.
A single positional rule (independent of the ID's Kind) keeps ref naming robust for legacy and ULID IDs alike and impossible to compute inconsistently between callers. The suffix spreads checkpoints evenly across buckets for either format: a legacy hex ID is random throughout, and a ULID's leading characters encode its timestamp (barely varying between nearby checkpoints) while its trailing characters are random — so sharding on the suffix keeps the distribution even while the ID itself stays lexicographically sortable.
This is the git-refs ref namespace only; the entire/checkpoints/v1 branch tree keeps its own independent first-two layout (see Path). For an ID shorter than two characters the whole ID is returned.
func (CheckpointID) String ¶
func (id CheckpointID) String() string
String returns the checkpoint ID as a string.
func (*CheckpointID) UnmarshalJSON ¶
func (id *CheckpointID) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler with validation. Returns an error unless the JSON string is a valid checkpoint ID (12-char hex or ULID). Empty strings are allowed and result in EmptyCheckpointID.
Source Files