Documentation
¶
Overview ¶
Package key implements the 32-byte Amber-Store lookup key: a content address that encodes a CAS object type, a logical payload length, and a truncated BLAKE3 hash of the payload's serialized bytes. See architecture/keys.md.
Index ¶
Constants ¶
const GitSHA1Size = 20
GitSHA1Size is the byte length of the SHA-1 a GitSHA1 key holds.
const Size = 32
Size is the fixed byte length of every key.
Variables ¶
var ( // ErrBadKeyLength means the input to Parse was not exactly Size bytes. ErrBadKeyLength = errors.New("key: data is not 32 bytes") // ErrReservedBitSet means the header's reserved bit (bit 3) is set. ErrReservedBitSet = errors.New("key: reserved header bit is set") // ErrReservedType means the object type is reserved (7..15) or out of range. ErrReservedType = errors.New("key: reserved object type") // ErrNonCanonicalLength means the length field has leading-zero padding. ErrNonCanonicalLength = errors.New("key: non-canonical length encoding") // ErrNonCanonicalGitKey means a GitSHA1 key has something other than zeros // after its SHA-1. ErrNonCanonicalGitKey = errors.New("key: non-canonical git key") // ErrNotBlake3 means New or NewFromHash was asked for a type whose key does // not hold a BLAKE3 digest. NewGitSHA1 makes those keys. ErrNotBlake3 = errors.New("key: this type is not addressed by BLAKE3") )
Sentinel errors returned by Parse, Validate, and the constructors. Wrap them with %w and match with errors.Is.
Functions ¶
This section is empty.
Types ¶
type Key ¶
Key is a 32-byte lookup key. It is a value type and is directly comparable, so it can be used as a Go map key. Accessors assume the key is canonical (produced by New, NewFromHash, or Parse).
The bytes are the (header, length, hash) encoding of architecture/keys.md reversed: the truncated hash comes first and the header byte last, so keys sort and bucket uniformly on their leading bytes. A GitSHA1 key has a layout of its own, see NewGitSHA1.
func New ¶
New computes the BLAKE3-256 digest of serialized, then assembles a canonical key via NewFromHash. length is the logical payload length and is taken as given (it need not equal len(serialized) — see NewFromHash). A GitSHA1 key is not made here: see NewGitSHA1.
func NewFromHash ¶
NewFromHash assembles a canonical key from a CAS object type, a logical payload length, and a precomputed full 256-bit BLAKE3 digest. The digest is truncated to its leading bytes to fill the key, and the whole encoding is byte-reversed (see Key). length is used verbatim: for Blob/XattrSet it is the serialized byte length; for FileNode/DirLeaf/DirNode and Commit it is a logical size (see architecture/types.md). Returns ErrReservedType if t is not a defined type and ErrNotBlake3 if it is GitSHA1.
func NewGitSHA1 ¶ added in v0.11.0
func NewGitSHA1(sum [GitSHA1Size]byte) Key
NewGitSHA1 assembles the key of a git object from its SHA-1. The layout is not the reversed one: the SHA-1 comes first, in digest order, so a key's hex starts with the object's git id and keys sort as git ids do. Then come ten zero bytes, the length (a git object's id does not tell its size, so a key made from a link in another object could not hold one: it is always zero) and the header. See architecture/keys.md.
func Parse ¶
Parse copies b into a Key and validates its canonical form. b must be exactly Size bytes.
func (Key) GitSHA1Sum ¶ added in v0.11.0
func (k Key) GitSHA1Sum() (sum [GitSHA1Size]byte, ok bool)
GitSHA1Sum returns the SHA-1 a GitSHA1 key holds. ok is false for a key of any other type.
func (Key) Hash ¶
Hash returns the payload hash in digest order, a copy. For a BLAKE3 key that is the truncated digest (len == Size-1-LengthSize), which the key stores reversed; for a GitSHA1 key it is the SHA-1, GitSHA1Size bytes.
func (Key) Length ¶
Length decodes the payload-length field, which sits just before the header byte, least significant byte first.
func (Key) LengthSize ¶
LengthSize returns the number of bytes the payload-length field occupies (1..8).
func (Key) Validate ¶
Validate reports whether k is canonical: the reserved bit is clear, the type is defined (0..6), the length field is minimally encoded (its most significant byte, the one next to the header, is non-zero, except for the single 0x00 byte that encodes a zero length), and a GitSHA1 key has nothing but zeros after its SHA-1, so that one git object has one key.
type Type ¶
type Type uint8
Type is the 4-bit CAS object type carried in the high nibble of a key's header byte (architecture/types.md).
const ( Blob Type = 0 // raw file-content byte chunk (a CDC leaf) FileNode Type = 1 // file chunk-index node DirLeaf Type = 2 // a contiguous run of directory entries DirNode Type = 3 // directory index node XattrSet Type = 4 // spilled extended attributes Commit Type = 5 // snapshot record: tree, parent commits, author, committer, message GitSHA1 Type = 6 // a git object, addressed by its SHA-1 (architecture/git-objects.md) )
Source Files