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
• Variables
• 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) ActiveZone() string
  • func (r *Repo) AddZone(ctx context.Context, zoneName string) 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) (zoneName, branch string, commit store.Hash, err 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) StagedCount() int
  • func (r *Repo) Storage() store.Storage
  • func (r *Repo) SwitchZone(ctx context.Context, zoneName, branch string) error
  • func (r *Repo) Zones(ctx context.Context) ([]string, error)

Constants

const DefaultBranch = "main"

DefaultBranch is the branch new zones get on first init.

Variables

var ErrReadOnlyMigrationNeeded = errors.New("legacy v0.3 repo opened read-only; re-open writable to auto-migrate")

ErrReadOnlyMigrationNeeded is returned by Open when a v0.3 repo is opened read-only — migration is a write operation, so the user must re-open without ReadOnly to convert it. This keeps the daemon from silently mutating a repo a separate writer process is also holding.

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.

In v0.4 a repo can hold multiple zones. Mutations (Set, Delete, Commit) operate on the active zone — the zone HEAD currently points at. The CLI's `--zone` flag and the SwitchZone API move HEAD between zones. 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).

If the repo uses the v0.3 single-zone layout, Open returns ErrLegacyRepo with the legacy zone name in the wrapped message; the caller is expected to surface a migration instruction.

func (*Repo) ActiveZone

func (r *Repo) ActiveZone() string

ActiveZone returns the zone HEAD currently points at, or "" if HEAD is unset.

func (*Repo) AddZone

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

AddZone registers an additional zone without moving HEAD. Use this to host a second zone in an existing repo.

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 active branch (the branch HEAD points at), advances the branch ref, appends a reflog entry, and clears staging.

func (*Repo) Delete

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

Delete stages removal of (fqdn, rrtype). fqdn must be relative to the active 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) (zoneName, branch string, commit store.Hash, err error)

Head returns (zone, branch, commit) where (zone, branch) is what HEAD points at. 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. The zonefile is parsed against the active zone's apex.

func (*Repo) Init

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

Init creates an empty repo registering zone with a default branch and pointing HEAD at it. If the zone already exists, Init is a no-op for that zone and leaves HEAD alone.

Multi-zone repos call Init for the first zone and AddZone for each subsequent zone; behaviour is equivalent except Init also sets HEAD if it isn't already set.

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.

The RR owner name is interpreted relative to the active zone.

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) SwitchZone

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

SwitchZone moves HEAD to (zone, branch) and refreshes the cached active zone. The zone must already be registered; branch may or may not exist (orphan branches are allowed).

func (*Repo) Zones

func (r *Repo) Zones(ctx context.Context) ([]string, error)

Zones returns all registered zones in the repo, sorted.