repo

Documentation

Overview

Package repo is the public Go API of zonegit. It composes pkg/store, pkg/object, pkg/zone, pkg/refs, and pkg/history into a single Repo type with high-level operations that the CLI and server consume.

Anything embedding zonegit should depend on this package, never on the layers below.

Index

• Constants
• func MergeBase(ctx context.Context, s store.Storage, a, b store.Hash) (store.Hash, error)
• type MergeResult
• type Options
• type Repo
  • func Open(opts Options) (*Repo, error)
  • func (r *Repo) Blame(ctx context.Context, fqdn, rrtype string) (history.BlameInfo, error)
  • func (r *Repo) Close() error
  • func (r *Repo) Commit(ctx context.Context, author object.Identity, msg string) (store.Hash, error)
  • func (r *Repo) Delete(fqdn, rrtype string)
  • func (r *Repo) Diff(ctx context.Context, fromRefish, toRefish string) ([]history.Change, error)
  • func (r *Repo) Head(ctx context.Context) (string, store.Hash, error)
  • func (r *Repo) Import(ctx context.Context, src io.Reader) (int, error)
  • func (r *Repo) Init(ctx context.Context, zoneName string) error
  • func (r *Repo) Log(ctx context.Context, refish string, max int) ([]history.Entry, error)
  • func (r *Repo) Lookup(ctx context.Context, commit store.Hash, fqdn, rrtype string) (zone.RRset, error)
  • func (r *Repo) Merge(ctx context.Context, theirsBranch string, author object.Identity, msg string) (MergeResult, error)
  • func (r *Repo) Refs() *refs.DB
  • func (r *Repo) ResetHard(ctx context.Context, refish string, author object.Identity) (store.Hash, error)
  • func (r *Repo) Resolve(ctx context.Context, refish string) (store.Hash, error)
  • func (r *Repo) Revert(ctx context.Context, refish string, author object.Identity, msg string) (store.Hash, error)
  • func (r *Repo) Set(ctx context.Context, rrs []dns.RR) error
  • func (r *Repo) SetZone(z string)
  • func (r *Repo) StagedCount() int
  • func (r *Repo) Storage() store.Storage
  • func (r *Repo) Zone() string

Constants

const DefaultBranch = "main"

DefaultBranch is the branch v0 uses for new repos.

Functions

func MergeBase

func MergeBase(ctx context.Context, s store.Storage, a, b store.Hash) (store.Hash, error)

MergeBase returns the lowest common ancestor of two commits using a straightforward two-set traversal. Returns ZeroHash if there is none (independent histories).

Types

type MergeResult

type MergeResult struct {
	// FastForward is true when ours was an ancestor of theirs and the
	// branch was simply advanced (no merge commit produced).
	FastForward bool

	// AlreadyUpToDate is true when theirs was an ancestor of ours; nothing
	// to do.
	AlreadyUpToDate bool

	// Commit is the resulting commit hash on the current branch. ZeroHash
	// when AlreadyUpToDate or when conflicts prevented committing.
	Commit store.Hash

	// Conflicts lists per-leaf 3-way conflicts. When non-empty, no commit
	// is produced and the branch ref is unchanged.
	Conflicts []merge.Conflict
}

MergeResult describes the outcome of a Merge call.

type Options

type Options struct {
	// Storage to use. If non-nil, takes precedence over Path.
	Storage store.Storage
	// Path to a Badger directory. Used only if Storage is nil.
	Path string
	// Memory uses an in-memory store. Used only if Storage and Path are both empty.
	Memory bool
	// ReadOnly opens the underlying Badger store without acquiring the
	// directory lock, allowing multiple readers (and one concurrent writer)
	// to coexist. Only meaningful with Path. Mutating calls (Set/Delete/
	// Commit/Init) will fail with an error from BadgerDB.
	ReadOnly bool
}

Options for opening a Repo.

type Repo

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

Repo is the public zonegit handle.

A Repo is bound to one Storage and one zone (the zone name is part of init metadata so that label paths in trees can be relative to the zone apex). All write paths take a per-Repo write lock to avoid useless CAS retries against ourselves; concurrent readers are unblocked.

func Open

func Open(opts Options) (*Repo, error)

Open opens an existing repo or creates one if not present (when using a path-based Storage). The branch HEAD points at is loaded into memory.

func (*Repo) Blame

func (r *Repo) Blame(ctx context.Context, fqdn, rrtype string) (history.BlameInfo, error)

Blame returns the commit that introduced the current value of (fqdn, rrtype) at HEAD.

func (*Repo) Close

func (r *Repo) Close() error

Close releases the underlying storage.

func (*Repo) Commit

func (r *Repo) Commit(ctx context.Context, author object.Identity, msg string) (store.Hash, error)

Commit applies all staged edits as a single new commit on the current branch, advances HEAD, appends a reflog entry, and clears staging.

Returns the new commit hash.

func (*Repo) Delete

func (r *Repo) Delete(fqdn, rrtype string)

Delete stages removal of (fqdn, rrtype). fqdn must be relative to the zone apex ("" or "@" for the apex itself).

func (*Repo) Diff

func (r *Repo) Diff(ctx context.Context, fromRefish, toRefish string) ([]history.Change, error)

Diff computes the RRset-level changes between two ref-ish points.

func (*Repo) Head

func (r *Repo) Head(ctx context.Context) (string, store.Hash, error)

Head returns (branch, commit) where branch is "refs/heads/X". commit may be ZeroHash for an orphan branch.

func (*Repo) Import

func (r *Repo) Import(ctx context.Context, src io.Reader) (int, error)

Import reads a zonefile and stages a Set for every RRset it contains.

func (*Repo) Init

func (r *Repo) Init(ctx context.Context, zoneName string) error

Init creates an empty repo on the default branch with the given zone name. The zone name is persisted so subsequent opens (CLI invocations, the daemon) do not need an explicit --zone flag.

Init is idempotent: if HEAD is already set, it only refreshes the zone metadata.

func (*Repo) Log

func (r *Repo) Log(ctx context.Context, refish string, max int) ([]history.Entry, error)

Log returns up to max commits in first-parent order from refish (default HEAD if "").

func (*Repo) Lookup

func (r *Repo) Lookup(ctx context.Context, commit store.Hash, fqdn, rrtype string) (zone.RRset, error)

Lookup returns the canonical-form blob payload for (fqdn, rrtype) at the given commit (or HEAD if commit is zero). Returns ErrNotFound if absent.

func (*Repo) Merge

func (r *Repo) Merge(ctx context.Context, theirsBranch string, author object.Identity, msg string) (MergeResult, error)

Merge integrates the named branch into the current branch (the branch that HEAD points at).

Behavior matches Git's `git merge`:

• If our branch is an ancestor of theirs: fast-forward.
• If theirs is an ancestor of ours: already up to date.
• Otherwise: 3-way merge over trees. On conflicts we abort with a non-empty MergeResult.Conflicts and leave the branch unchanged.
• Otherwise: produce a merge commit with two parents.

Merge requires no staged changes (similar to Git's index check).

func (*Repo) Refs

func (r *Repo) Refs() *refs.DB

Refs returns the underlying refs.DB.

func (*Repo) ResetHard

func (r *Repo) ResetHard(ctx context.Context, refish string, author object.Identity) (store.Hash, error)

ResetHard moves the current branch ref to the commit identified by refish and clears any staged changes. There is no working-tree analogue in zonegit, so --hard and --mixed degenerate to the same operation; we name this method ResetHard to be explicit that it is destructive (the previous tip becomes unreachable from the branch).

func (*Repo) Resolve

func (r *Repo) Resolve(ctx context.Context, refish string) (store.Hash, error)

Resolve parses a ref-ish string (see refs.DB.Resolve for forms).

func (*Repo) Revert

func (r *Repo) Revert(ctx context.Context, refish string, author object.Identity, msg string) (store.Hash, error)

Revert produces a new commit on the current branch that is the inverse of the named commit (target). Specifically: it computes the tree diff between target and target's first parent and applies the *reversed* changes on top of the current branch HEAD.

If target has no parents (root commit), Revert removes every leaf introduced by it.

The returned hash is the new commit on the current branch. Returns an error if applying the inverse would conflict with the current state (the leaf to be reverted no longer matches target's "after" value).

func (*Repo) Set

func (r *Repo) Set(ctx context.Context, rrs []dns.RR) error

Set stages an RRset write to be applied on the next Commit. RRs are homogenized (same name/class/type/ttl) per pkg/zone rules.

func (*Repo) SetZone

func (r *Repo) SetZone(z string)

SetZone overrides the in-memory zone name (used by Open after restoring from disk; eventually we'll persist this).

func (*Repo) StagedCount

func (r *Repo) StagedCount() int

StagedCount returns the number of pending edits (used for `zonegit status`).

func (*Repo) Storage

func (r *Repo) Storage() store.Storage

Storage returns the underlying store.Storage. Useful for tests and for embedders that need lower-level access.

func (*Repo) Zone

func (r *Repo) Zone() string

Zone returns the canonical zone name (with trailing dot).