object

Documentation

Overview

Package object defines the four immutable content-addressable object kinds that constitute a zonegit repository: Blob, Tree, Commit, Tag.

See docs/OBJECT_MODEL.md for the canonical encoding and invariants. This package is DNS-unaware: a Blob's payload is opaque bytes that pkg/zone has already canonicalized.

Index

• func Encode(kind Kind, payload []byte) (store.Hash, store.Object)
• func HashOf(kind Kind, payload []byte) store.Hash
• func PutTree(ctx context.Context, s store.Storage, t Tree) (store.Hash, error)
• func UpdateTree(ctx context.Context, s store.Storage, root store.Hash, path []string, ...) (store.Hash, error)
• func Verify(h store.Hash, obj store.Object) error
• func WalkAllLeaves(ctx context.Context, s store.Storage, root store.Hash, ...) error
• func WalkTree(ctx context.Context, s store.Storage, root store.Hash, path []string, ...) (store.Hash, error)
• type Blob
  • func DecodeBlob(payload []byte) Blob
  • func (b Blob) Encode() (store.Hash, store.Object)
• type Commit
  • func DecodeCommit(payload []byte) (Commit, error)
  • func (c Commit) Encode() (store.Hash, store.Object)
• type EntryKind
  • func (k EntryKind) IsValid() bool
• type Identity
  • func (id Identity) String() string
• type Kind
  • func (k Kind) IsValid() bool
• type Tag
  • func DecodeTag(payload []byte) (Tag, error)
  • func (t Tag) Encode() (store.Hash, store.Object)
• type Tree
  • func DecodeTree(payload []byte) (Tree, error)
  • func LoadTree(ctx context.Context, s store.Storage, h store.Hash) (Tree, error)
  • func (t Tree) Encode() (store.Hash, store.Object)
  • func (t Tree) Get(kind EntryKind, name string) (TreeEntry, bool)
• type TreeEntry

Functions

func Encode

func Encode(kind Kind, payload []byte) (store.Hash, store.Object)

Encode is a small convenience: returns both the hash and a store.Object ready to pass to PutObject.

func HashOf

func HashOf(kind Kind, payload []byte) store.Hash

HashOf computes the content address for (kind, payload):

SHA256( "<kind> <decimal-len>\x00" || payload )

This is the single source of truth for object identity.

func PutTree

func PutTree(ctx context.Context, s store.Storage, t Tree) (store.Hash, error)

PutTree encodes t and writes it to s. Returns the hash.

func UpdateTree

func UpdateTree(ctx context.Context, s store.Storage, root store.Hash, path []string, rrtype string, leafHash store.Hash) (store.Hash, error)

UpdateTree returns the new root hash of a tree where the leaf (path, rrtype) is set to leafHash.

If leafHash is zero, the leaf is removed; if removing it leaves a Tree node empty, that subtree is also pruned (and so on recursively, except for the top-level zone root which is allowed to be empty).

Pre-existing path elements that are unchanged are reused by hash — only the spine from leaf to root is rewritten. This is what makes committing a single-RR change cost ~O(zone-depth) writes regardless of total zone size.

All new Tree objects are written to s; the caller is responsible for updating the ref pointing at the new root.

func Verify

func Verify(h store.Hash, obj store.Object) error

Verify checks that obj's bytes hash to h. It is the caller's only defense against silent on-disk corruption.

func WalkAllLeaves

func WalkAllLeaves(ctx context.Context, s store.Storage, root store.Hash, fn func(path []string, rrtype string, blobHash store.Hash) error) error

WalkAllLeaves visits every leaf (RRset) reachable from root in depth-first, sorted order. The callback receives the labels path from the zone apex down to (but excluding) the leaf, plus the leaf's name (RR-type mnemonic) and blob hash.

This is the enumeration AXFR and zone-export workflows need.

func WalkTree

func WalkTree(ctx context.Context, s store.Storage, root store.Hash, path []string, rrtype string) (store.Hash, error)

WalkTree traverses path through nested Tree objects starting at root, then returns the leaf entry whose Name matches rrtype. Each path element is a single DNS label (e.g. ["api"] for api.<zone>).

Returns store.ErrNotFound if any intermediate label or the final rrtype leaf is absent.

Types

type Blob

type Blob struct {
	Payload []byte
}

Blob is the content-addressable form of one RRset.

Payload is the canonical RRset bytes per docs/OBJECT_MODEL.md section 4. pkg/object treats Payload as opaque: it is the responsibility of pkg/zone to produce the canonical byte form (lowercase owner, sorted rdata, etc.). This split keeps pkg/object DNS-unaware and trivially testable.

func DecodeBlob

func DecodeBlob(payload []byte) Blob

DecodeBlob lifts a payload back into a Blob. It cannot fail because the payload is opaque; format errors surface only when pkg/zone tries to parse it as an RRset.

func (Blob) Encode

func (b Blob) Encode() (store.Hash, store.Object)

Encode returns the hash and store.Object for this blob.

type Commit

type Commit struct {
	Tree       store.Hash
	Parents    []store.Hash
	Author     Identity
	Committer  Identity
	AuthorTime time.Time
	CommitTime time.Time
	Selector   string // optional, for canary commits (v2+)
	Signature  string // optional, populated in v3
	Message    string
}

Commit is the user-facing form of a commit object.

On-disk format is line-oriented text per docs/OBJECT_MODEL.md section 6:

version 1
tree <hex>
parent <hex>           (zero or more)
author Name <email> <unix> <±HHMM>
committer Name <email> <unix> <±HHMM>
[selector <expr>]      (optional, reserved for v2 canary)
[signature ed25519 <base64>] (optional, populated in v3)

<message>

Header order is fixed where it matters (tree first; parents in order; author then committer). A blank line separates headers from message.

func DecodeCommit

func DecodeCommit(payload []byte) (Commit, error)

DecodeCommit parses a commit payload.

func (Commit) Encode

func (c Commit) Encode() (store.Hash, store.Object)

Encode renders c in canonical text form and returns (hash, object).

type EntryKind

type EntryKind uint8

EntryKind distinguishes a subtree pointer from a leaf RRset pointer inside a Tree. The byte values are part of the on-disk canonical form; do NOT renumber.

const (
	EntrySubtree EntryKind = 0 // points to another Tree object
	EntryLeaf    EntryKind = 1 // points to a Blob (RRset)
)

func (EntryKind) IsValid

func (k EntryKind) IsValid() bool

IsValid reports whether k is a defined EntryKind.

type Identity

type Identity struct {
	Name  string
	Email string
}

Identity is a name/email pair used for authors, committers, taggers.

func (Identity) String

func (id Identity) String() string

String renders as "Name <email>". Empty fields are tolerated by the parser but discouraged.

type Kind

type Kind string

Kind is the type tag of a content-addressable object. The string values match the on-disk header tag in docs/OBJECT_MODEL.md section 3.

const (
	KindBlob   Kind = "blob"
	KindTree   Kind = "tree"
	KindCommit Kind = "commit"
	KindTag    Kind = "tag"
	// KindSymref is the object kind for symbolic refs (HEAD). Payload is
	// the raw UTF-8 target ref path (e.g. "refs/heads/foo.com./main").
	// Stored via the object store so HEAD targets are not constrained by
	// the 31-byte ref-value slot.
	KindSymref Kind = "symref"
)

func (Kind) IsValid

func (k Kind) IsValid() bool

IsValid reports whether k is one of the canonical kinds.

type Tag

type Tag struct {
	Object     store.Hash
	Type       string // typically "commit"
	Tag        string // tag name, e.g. "v2026.04.25-prod"
	Tagger     Identity
	TaggerTime time.Time
	Signature  string // optional
	Message    string
}

Tag is an immutable named pointer with an optional message and signature.

Format mirrors Commit's text-line scheme; see docs/OBJECT_MODEL.md section 7.

func DecodeTag

func DecodeTag(payload []byte) (Tag, error)

DecodeTag parses a tag payload.

func (Tag) Encode

func (t Tag) Encode() (store.Hash, store.Object)

Encode renders t in canonical form and returns (hash, object).

type Tree

type Tree struct {
	Entries []TreeEntry
}

Tree is a sorted list of TreeEntry. Sorting is enforced at encode time; callers may build entries in any order and the encoded bytes will still canonicalize.

func DecodeTree

func DecodeTree(payload []byte) (Tree, error)

DecodeTree parses a tree payload. It validates structure and sort order: trees that decode but were not produced by Encode (e.g. unsorted) are rejected, since accepting them would let two trees with the same logical content have two different hashes.

func LoadTree

func LoadTree(ctx context.Context, s store.Storage, h store.Hash) (Tree, error)

LoadTree fetches a Tree by hash from a Storage.

func (Tree) Encode

func (t Tree) Encode() (store.Hash, store.Object)

Encode produces (hash, store.Object) for this tree.

On-disk layout per docs/OBJECT_MODEL.md section 5:

version    : uint8
entry_count: uvarint
for each entry (sorted):
    kind_byte : uint8
    name_len  : uint8
    name      : []byte
    hash      : [32]byte

Sort order is (kind ASC, name ASC). All subtrees come before leaves at the same level because EntrySubtree (0) < EntryLeaf (1).

func (Tree) Get

func (t Tree) Get(kind EntryKind, name string) (TreeEntry, bool)

Get returns the entry with (kind, name) and reports whether it exists. Lookup is O(log n) since entries are kept sorted by Encode/Decode.

type TreeEntry

type TreeEntry struct {
	Kind EntryKind
	Name string
	Hash store.Hash
}

TreeEntry is one row of a Tree node.

• For EntrySubtree, Name is a single DNS label (lowercase, byte-compared) and Hash points to the child Tree.
• For EntryLeaf, Name is a DNS RR-type mnemonic ("A", "AAAA", "MX", ...) in uppercase ASCII and Hash points to a Blob.

Name is constrained to 0..255 bytes by the on-disk format.