object

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package object implements the content-addressed object store for graft, supporting SHA-256 hashed blobs, entities, entity lists, trees, commits, and tags with zlib compression and pack file delta encoding.

Index

Constants

View Source 
const (
	// Tree mode constants compatible with Git's canonical mode strings.
	TreeModeDir        = "40000"
	TreeModeFile       = "100644"
	TreeModeExecutable = "100755"
	TreeModeModule     = "160000"
)

Variables

This section is empty.

Functions

func CommitSigningPayload 

func CommitSigningPayload(c *CommitObj) []byte

CommitSigningPayload returns the canonical bytes that are signed for a commit. The payload intentionally excludes the signature field itself.

func CompressPackPayload 

func CompressPackPayload(raw []byte) ([]byte, error)

CompressPackPayload zlib-compresses a raw pack payload so callers can parallelize pack preparation before serial pack writing.

func MarshalBlob 

func MarshalBlob(b *Blob) []byte

MarshalBlob serializes a Blob to raw bytes (identity).

func MarshalCommit 

func MarshalCommit(c *CommitObj) []byte

MarshalCommit serializes a CommitObj: 

tree H
parent H               (zero or more)
author A
timestamp T
author_tz TZ           (optional)
committer C            (optional)
committer_timestamp T  (optional)
committer_tz TZ        (optional)
signature S            (optional)

message

func MarshalEntity 

func MarshalEntity(e *EntityObj) []byte

MarshalEntity serializes an EntityObj to a deterministic text format: 

kind X
name Y
declkind Z
receiver R
bodyhash H

<body bytes>

func MarshalEntityList 

func MarshalEntityList(el *EntityListObj) []byte

MarshalEntityList serializes an EntityListObj: 

language X
path Y

hash1
hash2
...

func MarshalPackEntityTrailer 

func MarshalPackEntityTrailer(entries []PackEntityTrailerEntry) ([]byte, error)

MarshalPackEntityTrailer serializes entries to the Graft pack trailer format.

func MarshalTag 

func MarshalTag(t *TagObj) []byte

MarshalTag serializes a TagObj: 

version X
target H

<tag bytes>

func MarshalTree 

func MarshalTree(tr *TreeObj) []byte

MarshalTree serializes a TreeObj. Entries are sorted by Name for deterministic output. Each entry is one line: 

name mode blobhash entitylisthash subtreehash

where mode is a Git-compatible mode string (e.g. 40000, 100644, 100755), and empty hashes are represented as "-".

func ValidateHash 

func ValidateHash(s string) error

ValidateHash checks that s is a well-formed 64-character lowercase hex hash. Returns an error if the hash is invalid.

Types

type Blob 

type Blob struct {
	Data []byte
}

Blob holds raw file data.

func UnmarshalBlob 

func UnmarshalBlob(data []byte) (*Blob, error)

UnmarshalBlob deserializes raw bytes into a Blob and copies input data. This preserves ownership semantics for callers that reuse input buffers.

func UnmarshalBlobNoCopy 

func UnmarshalBlobNoCopy(data []byte) (*Blob, error)

UnmarshalBlobNoCopy deserializes raw bytes into a Blob without copying. The returned Blob aliases data; callers must keep data immutable while the Blob is in use.

type CommitObj 

type CommitObj struct {
	TreeHash           Hash
	Parents            []Hash
	Author             string
	Timestamp          int64
	AuthorTimezone     string
	Committer          string
	CommitterTimestamp int64
	CommitterTimezone  string
	Signature          string
	Message            string
}

CommitObj represents a commit pointing to a tree with metadata.

func UnmarshalCommit 

func UnmarshalCommit(data []byte) (*CommitObj, error)

UnmarshalCommit parses a CommitObj from its serialized form.

type EntityListObj 

type EntityListObj struct {
	Language   string
	Path       string
	EntityRefs []Hash // ordered refs to EntityObj hashes
}

EntityListObj is an ordered list of entity references for a file.

func UnmarshalEntityList 

func UnmarshalEntityList(data []byte) (*EntityListObj, error)

UnmarshalEntityList parses an EntityListObj from its serialized form.

type EntityObj 

type EntityObj struct {
	Kind     string // e.g. "function", "type", "method"
	Name     string
	DeclKind string // language-specific declaration kind
	Receiver string // method receiver, empty for non-methods
	Body     []byte
	BodyHash Hash
}

EntityObj represents a single code entity (function, type, etc.).

func UnmarshalEntity 

func UnmarshalEntity(data []byte) (*EntityObj, error)

UnmarshalEntity parses an EntityObj from its serialized form.

type GCSummary 

type GCSummary struct {
	PackedObjects int
	PrunedObjects int
	PackFile      string
	IndexFile     string
}

GCSummary reports the outcome of Store.GC.

type Hash 

type Hash string

Hash is a 64-character hex-encoded SHA-256 digest.

func HashBytes 

func HashBytes(data []byte) Hash

HashBytes computes the raw SHA-256 hash of data and returns it as a lowercase hex-encoded Hash.

func HashObject 

func HashObject(objType ObjectType, data []byte) Hash

HashObject computes the SHA-256 of the envelope "type len\0content", mirroring Git's object hashing but with SHA-256.

func WritePackEntityTrailer 

func WritePackEntityTrailer(w io.Writer, entries []PackEntityTrailerEntry) (Hash, error)

WritePackEntityTrailer writes the encoded trailer and returns its checksum.

func WritePackIndex 

func WritePackIndex(w io.Writer, entries []PackIndexEntry, packChecksum Hash) (Hash, error)

WritePackIndex writes a Git idx v2 style index for the provided entries and pack checksum. It returns the hex-encoded index checksum.

type ObjectType 

type ObjectType string

ObjectType identifies the kind of object stored. 

const (
	TypeBlob       ObjectType = "blob"
	TypeTag        ObjectType = "tag"
	TypeEntity     ObjectType = "entity"
	TypeEntityList ObjectType = "entitylist"
	TypeTree       ObjectType = "tree"
	TypeCommit     ObjectType = "commit"
)

type PackEntityTrailer 

type PackEntityTrailer struct {
	Version  uint16
	Entries  []PackEntityTrailerEntry
	Checksum Hash
}

PackEntityTrailer is the parsed Graft-specific pack extension trailer.

func ReadPackEntityTrailer 

func ReadPackEntityTrailer(data []byte) (*PackEntityTrailer, error)

ReadPackEntityTrailer parses and validates a full trailer byte slice.

type PackEntityTrailerEntry 

type PackEntityTrailerEntry struct {
	ObjectHash Hash
	StableID   string
}

PackEntityTrailerEntry maps one object hash to an entity stable identifier.

type PackEntry 

type PackEntry struct {
	Type         PackObjectType
	OriginalType PackObjectType
	Size         uint64
	Data         []byte
	Offset       uint64
	BaseDistance uint64 // populated for OFS_DELTA entries
	BaseRef      Hash   // populated for REF_DELTA entries
}

PackEntry represents one object entry in a pack stream.

func ResolvePackEntries 

func ResolvePackEntries(entries []PackEntry) ([]PackEntry, error)

ResolvePackEntries resolves OFS_DELTA and REF_DELTA entries to full object contents. Returned entries preserve OriginalType while Type is set to the resolved concrete object type.

type PackFile 

type PackFile struct {
	Header        PackHeader
	Entries       []PackEntry
	Checksum      Hash
	EntityTrailer *PackEntityTrailer
}

PackFile is the decoded content of a full pack stream.

func ReadPack 

func ReadPack(data []byte) (*PackFile, error)

ReadPack parses a full pack file byte slice, verifies trailer checksum, and returns decoded entries.

func ReadPackFromReader 

func ReadPackFromReader(r io.Reader) (*PackFile, error)

ReadPackFromReader reads a complete pack stream from r and delegates to ReadPack for decode and verification.

func ReadPackResolved 

func ReadPackResolved(data []byte) (*PackFile, error)

ReadPackResolved parses and resolves delta entries to their materialized object contents.

type PackHeader 

type PackHeader struct {
	Version    uint32
	NumObjects uint32
}

PackHeader is the fixed-size Git pack header.

Bytes:

  • 0..3: "PACK"
  • 4..7: version (big-endian)
  • 8..11: number of objects (big-endian)

func UnmarshalPackHeader 

func UnmarshalPackHeader(data []byte) (*PackHeader, error)

UnmarshalPackHeader parses a canonical Git pack header.

func (PackHeader) Marshal 

func (h PackHeader) Marshal() []byte

Marshal serializes the header to the canonical 12-byte pack header.

type PackIndex 

type PackIndex struct {
	PackChecksum  Hash
	IndexChecksum Hash
	// contains filtered or unexported fields
}

PackIndex is an in-memory representation of an idx v2 file.

func ReadPackIndex 

func ReadPackIndex(data []byte) (*PackIndex, error)

ReadPackIndex parses and validates an idx v2 file.

func ReadPackIndexFromReader 

func ReadPackIndexFromReader(r io.Reader) (*PackIndex, error)

ReadPackIndexFromReader parses an idx v2 stream.

func (*PackIndex) Entries 

func (idx *PackIndex) Entries() []PackIndexEntry

Entries returns a copy of all index entries in lexicographic hash order.

func (*PackIndex) Find 

func (idx *PackIndex) Find(h Hash) (PackIndexEntry, bool)

Find performs fanout-bounded binary search for a hash in the index.

type PackIndexEntry 

type PackIndexEntry struct {
	Hash   Hash
	Offset uint64
	CRC32  uint32
}

PackIndexEntry is one row in a pack index file.

type PackObjectType 

type PackObjectType uint8

PackObjectType is the Git pack object type encoding used in object entry headers. Values match the canonical Git wire/storage format. 

const (
	PackCommit   PackObjectType = 1
	PackTree     PackObjectType = 2
	PackBlob     PackObjectType = 3
	PackTag      PackObjectType = 4
	PackOfsDelta PackObjectType = 6
	PackRefDelta PackObjectType = 7
)

type PackWriter 

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

PackWriter writes Git-compatible pack streams with zlib-compressed object entries. The trailer checksum is SHA-256 over all bytes preceding the trailer.

func NewPackWriter 

func NewPackWriter(out io.Writer, numObjects uint32) (*PackWriter, error)

NewPackWriter initializes a new writer and writes the fixed pack header.

func (*PackWriter) CurrentOffset 

func (p *PackWriter) CurrentOffset() uint64

CurrentOffset returns the current byte offset in the pack stream (from pack start), excluding the trailing checksum written by Finish().

func (*PackWriter) Finish 

func (p *PackWriter) Finish() (Hash, error)

Finish validates object count, writes the trailing pack checksum, and returns that checksum as a hex digest.

func (*PackWriter) FinishWithEntityTrailer 

func (p *PackWriter) FinishWithEntityTrailer(entries []PackEntityTrailerEntry) (Hash, error)

FinishWithEntityTrailer behaves like Finish and additionally appends the Graft-specific entity trailer after the standard pack checksum.

func (*PackWriter) WriteCompressedEntry 

func (p *PackWriter) WriteCompressedEntry(objType PackObjectType, rawSize uint64, compressed []byte) error

WriteCompressedEntry appends an already-compressed object entry. The caller is responsible for passing the uncompressed object size alongside the exact zlib-compressed payload bytes for that object.

func (*PackWriter) WriteEntry 

func (p *PackWriter) WriteEntry(objType PackObjectType, data []byte) error

WriteEntry appends one object entry to the pack stream.

func (*PackWriter) WriteOfsDelta 

func (p *PackWriter) WriteOfsDelta(baseOffset uint64, baseData, targetData []byte) error

WriteOfsDelta writes an OFS_DELTA entry using an insert-only delta stream.

type Store 

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

Store is a content-addressed object store with a 2-character fan-out directory layout: objects/ab/cdef0123...

func NewStore 

func NewStore(root string) *Store

NewStore creates a Store rooted at the given directory. The objects/ subdirectory is created lazily on first write.

func (*Store) GC 

func (s *Store) GC() (*GCSummary, error)

GC packs all loose objects that are not already indexed by an existing pack idx. After a successful pack+index write, packed loose objects are removed.

func (*Store) GCReachable 

func (s *Store) GCReachable(roots []Hash) (*GCSummary, error)

GCReachable packs loose objects reachable from roots that are not already indexed by an existing pack idx. After a successful pack+index write, packed loose objects are removed.

func (*Store) Has 

func (s *Store) Has(h Hash) bool

Has reports whether the store contains an object with the given hash.

func (*Store) InvalidatePackIndexCache 

func (s *Store) InvalidatePackIndexCache()

InvalidatePackIndexCache drops all cached pack indices, forcing a re-read on the next access. This is useful after GC or external pack modifications.

func (*Store) ReachableSet 

func (s *Store) ReachableSet(roots []Hash) (map[Hash]struct{}, error)

ReachableSet returns all object hashes reachable from roots by following object references. Missing roots are ignored.

func (*Store) Read 

func (s *Store) Read(h Hash) (ObjectType, []byte, error)

Read retrieves an object by hash, returning its type and raw content.

func (*Store) ReadBlob 

func (s *Store) ReadBlob(h Hash) (*Blob, error)

ReadBlob reads and deserializes a Blob.

func (*Store) ReadCommit 

func (s *Store) ReadCommit(h Hash) (*CommitObj, error)

ReadCommit reads and deserializes a CommitObj.

func (*Store) ReadEntity 

func (s *Store) ReadEntity(h Hash) (*EntityObj, error)

ReadEntity reads and deserializes an EntityObj.

func (*Store) ReadEntityList 

func (s *Store) ReadEntityList(h Hash) (*EntityListObj, error)

ReadEntityList reads and deserializes an EntityListObj.

func (*Store) ReadTag 

func (s *Store) ReadTag(h Hash) (*TagObj, error)

ReadTag reads and deserializes a TagObj.

func (*Store) ReadTree 

func (s *Store) ReadTree(h Hash) (*TreeObj, error)

ReadTree reads and deserializes a TreeObj.

func (*Store) Verify 

func (s *Store) Verify() (*VerifySummary, error)

Verify checks object integrity across loose objects and pack/index entries.

func (*Store) Write 

func (s *Store) Write(objType ObjectType, data []byte) (Hash, error)

Write stores an object and returns its content hash. The on-disk format is zlib("type len\0content"). Writes are atomic: data is written to a temp file and then renamed into place.

func (*Store) WriteBlob 

func (s *Store) WriteBlob(b *Blob) (Hash, error)

WriteBlob serializes and stores a Blob.

func (*Store) WriteCommit 

func (s *Store) WriteCommit(c *CommitObj) (Hash, error)

WriteCommit serializes and stores a CommitObj.

func (*Store) WriteEntity 

func (s *Store) WriteEntity(e *EntityObj) (Hash, error)

WriteEntity serializes and stores an EntityObj.

func (*Store) WriteEntityList 

func (s *Store) WriteEntityList(el *EntityListObj) (Hash, error)

WriteEntityList serializes and stores an EntityListObj.

func (*Store) WriteTag 

func (s *Store) WriteTag(t *TagObj) (Hash, error)

WriteTag serializes and stores a TagObj.

func (*Store) WriteTree 

func (s *Store) WriteTree(tr *TreeObj) (Hash, error)

WriteTree serializes and stores a TreeObj.

type TagObj 

type TagObj struct {
	TargetHash Hash
	Data       []byte
}

TagObj preserves annotated tag payload while tracking the referenced object. Data stores the canonical tag bytes, where the "object" header points at the graft hash (not git hash) so graph traversal can stay in graft object space.

func UnmarshalTag 

func UnmarshalTag(data []byte) (*TagObj, error)

UnmarshalTag parses a TagObj from its serialized form.

type TreeEntry 

type TreeEntry struct {
	Name           string
	IsDir          bool
	Mode           string
	BlobHash       Hash
	EntityListHash Hash
	SubtreeHash    Hash
}

TreeEntry is one entry in a tree object.

type TreeObj 

type TreeObj struct {
	Entries []TreeEntry // sorted by Name
}

TreeObj holds a sorted list of tree entries.

func UnmarshalTree 

func UnmarshalTree(data []byte) (*TreeObj, error)

UnmarshalTree parses a TreeObj from its serialized form.

type VerifySummary 

type VerifySummary struct {
	LooseObjects int
	PackFiles    int
	PackObjects  int
}

VerifySummary reports the outcome of Store.Verify.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.