object

package
v0.6.1 Latest Latest
Warning

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

Go to latest
Published: Sep 13, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package object implements content-addressed immutable objects.

Objects are identified by a BLAKE3 hash of their encoded form. This gives content addressing: identical content always maps to the same id, so objects can be deduplicated and stored immutably. An object is either a Blob (file bytes), a Tree (a directory listing of named entries), or a Conflict.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BlobToString

func BlobToString(data []byte) string

BlobToString is a small helper used for debug rendering of blob contents.

func EncodeObject

func EncodeObject(o *Object) ([]byte, error)

EncodeObject serializes an object into its canonical byte form used for storage. It is the inverse of DecodeObject. Trees use the compact binary encoding; blob content is raw bytes.

func EncodeTreeBytes

func EncodeTreeBytes(t *Tree) []byte

EncodeTreeBytes binary-encodes a tree (compact: varint count + per-entry name/kind/id). It replaces the old line-text form which bloat for trees with many files. The encoded payload is prefixed with the treeMagic marker so a blob can be distinguished from a tree without ambiguity.

func IsConflictObject

func IsConflictObject(k Kind) bool

IsConflictObject reports whether an object kind is a conflict.

func IsConflictPayload

func IsConflictPayload(payload []byte) bool

IsConflictPayload reports whether a payload looks like an encoded conflict.

func RandomRevisionID

func RandomRevisionID() (string, error)

RandomRevisionID returns a random 16-byte revision id encoded as 32 hex chars. revision ids are generated once and never change (content-independent), unlike object ids which are derived from content.

Types

type Conflict

type Conflict struct {
	Removes []Term
	Adds    []Term
}

Conflict is an N-way merge conflict, expressed as a set of negative terms (the base versions, "removes") and positive terms (the side versions, "adds"). This mirrors jj's `Merge<T>` where a 3-way conflict is represented as [-base, +ours, +theirs]; a conflict can generalize to any number of terms. Each term references a blob id plus a human label describing where it came from.

func NewConflictFrom3Way

func NewConflictFrom3Way(base, ours, theirs ID) *Conflict

NewConflictFrom3Way builds a conflict from a classic 3-way merge: base is negative; ours and theirs are positive.

func (*Conflict) Numeric

func (c *Conflict) Numeric() int

Numeric returns the number of terms (removes + adds).

type Entry

type Entry struct {
	Name string
	ID   ID
	Kind Kind
}

Entry is a named child object inside a Tree.

type ID

type ID [32]byte

ID is a content-addressed object identifier (32-byte BLAKE3 digest).

func BlobID

func BlobID(data []byte) ID

BlobID computes the content id of raw bytes.

func HashID

func HashID(o *Object, context []byte) ID

HashID computes the content id of an object. The optional context is mixed into the hash so callers can namespace hashes if needed.

func HexToID

func HexToID(s string) (ID, error)

HexToID decodes a hex string into an ID.

func (ID) IsZero

func (o ID) IsZero() bool

IsZero reports whether the ID is the zero value (no object).

func (ID) String

func (o ID) String() string

String returns the lowercase hex encoding of the ID.

type Kind

type Kind uint8

Kind discriminates the type of an object.

const (
	KindBlob Kind = iota
	KindTree
	KindConflict
)

Object kinds.

func (Kind) String

func (k Kind) String() string

type Object

type Object struct {
	Kind     Kind
	Blob     []byte
	Tree     *Tree
	Conflict *Conflict
}

Object is a decoded immutable object.

func DecodeObject

func DecodeObject(id ID, payload []byte) (*Object, error)

DecodeObject parses the canonical byte form back into an Object. id is the content id the caller expects; it is recorded on the object so callers can sanity check. Trees are recognized by the presence of the compact binary encoding (whose first field is a varint); blob content is passed through.

func (*Object) ID

func (o *Object) ID() ID

ID computes and returns the content-addressed id of the object.

type Term

type Term struct {
	ID    ID
	Label string
}

Term is one side of a conflict: a blob id plus a label.

type Tree

type Tree struct {
	Entries map[string]Entry
}

Tree is a directory: a sorted map of entry name -> entry.

func DecodeTreeBytes

func DecodeTreeBytes(payload []byte) *Tree

DecodeTreeBytes decodes a binary tree. It expects the payload WITHOUT the treeMagic prefix (callers strip it after detection).

func NewTree

func NewTree() *Tree

NewTree returns an empty tree.

func (*Tree) ID

func (t *Tree) ID() ID

ID returns the content-addressed id of this tree.

func (*Tree) SortedEntries

func (t *Tree) SortedEntries() []Entry

SortedEntries returns the entries in lexicographical order.

Jump to

Keyboard shortcuts

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