gitops

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2026 License: MPL-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package gitops implements the coordination control plane over an ordinary Git repository (ADR 0004).

Layout, from docs/spec/schemas.md and product scope §8: 

fxvcs.yaml               Stack: composition, components, mounts
runtime-resources.yaml   RuntimeResourceCatalog: runtime:/external: entries
resource-overrides.yaml  ResourceOverrides: sparse activation/order overrides
releases/<name>.yaml     Release (immutable once committed)
environments/<name>.yaml Environment
targets/<name>.yaml      Target

Every write lands in the working tree as reviewable YAML. Nothing here runs `git commit`, `git push`, or `git tag`: making a change authoritative is a human/CI review step, which is the whole point of a GitOps control plane.

Index

Constants

View Source 
const (
	StackFile            = "fxvcs.yaml"
	RuntimeResourcesFile = "runtime-resources.yaml"
	OverridesFile        = "resource-overrides.yaml"
	ReleasesDir          = "releases"
	EnvironmentsDir      = "environments"
	TargetsDir           = "targets"
)

File names and directories of the coordination layout.

Variables

View Source 
var ErrNotStack = errors.New("gitops: not a coordination repository")

ErrNotStack is returned when no coordination repository is found.

Functions

func IsCommitID 

func IsCommitID(s string) bool

IsCommitID reports whether s is a full SHA-1 or SHA-256 object name.

func LoadStack 

func LoadStack(root string) (*domain.Stack, error)

LoadStack reads and validates fxvcs.yaml at the given repository root without opening Git or enforcing the installed-version compatibility gate.

func Locate 

func Locate(start string) (string, error)

Locate walks up from start to the directory holding fxvcs.yaml.

func ValidateName 

func ValidateName(kind, name string) error

ValidateName checks a release, environment, or target name.

Types

type DocumentError 

type DocumentError struct {
	File string
	Err  error
}

DocumentError names the file a validation failure came from.

func (*DocumentError) Error 

func (e *DocumentError) Error() string

func (*DocumentError) Unwrap 

func (e *DocumentError) Unwrap() error

type FS 

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

FS presents a pinned component commit as a read-only fs.FS so the FiveM discovery and manifest-sandbox packages can scan it exactly as they scan a working tree. Release creation must re-scan the *pinned* tree, not whatever happens to be checked out, and this is the seam that makes those two code paths the same code path.

Blob contents are read on demand and memoised; directory structure is derived once from `ls-tree -r`. Symlinks and gitlinks are not exposed: a manifest scanner that followed one could leave the commit it is supposed to be describing.

func (*FS) Entry 

func (f *FS) Entry(p string) (TreeEntry, bool)

Entry returns the tree entry for a path.

func (*FS) Open 

func (f *FS) Open(name string) (fs.File, error)

Open implements fs.FS.

func (*FS) PathList 

func (f *FS) PathList() []string

PathList returns every regular file path in the tree, sorted.

func (*FS) ReadDir 

func (f *FS) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir implements fs.ReadDirFS.

func (*FS) ReadFile 

func (f *FS) ReadFile(name string) ([]byte, error)

ReadFile implements fs.ReadFileFS.

func (*FS) Stat 

func (f *FS) Stat(name string) (fs.FileInfo, error)

Stat implements fs.StatFS.

type Options 

type Options struct {
	Installed     format.Version
	GitExecutable string
}

Options configures Open.

type Repo 

type Repo struct {
	// Root is the working-tree top level holding fxvcs.yaml.
	Root string
	// GitDir is the coordination repository's $GIT_DIR; component mirrors and
	// other derived state live under GitDir/fxvcs.
	GitDir string
	// Stack is the parsed fxvcs.yaml.
	Stack *domain.Stack
	// Git runs against Root.
	Git *gitclient.Client
	// contains filtered or unexported fields
}

Repo is an opened coordination repository.

func Init 

func Init(ctx context.Context, root string, ws *domain.Stack, adopt bool, opts Options) (*Repo, error)

Init creates or adopts a coordination repository at root. The directory must already be a Git working tree (`stack init` refuses to guess where a new repository belongs); an existing fxvcs.yaml is an error unless adopt is set, in which case the existing file is loaded unchanged.

func Open 

func Open(ctx context.Context, start string, opts Options) (*Repo, error)

Open locates and loads the coordination repository containing start.

func OpenAt 

func OpenAt(ctx context.Context, root string, opts Options) (*Repo, error)

OpenAt loads the coordination repository rooted exactly at root.

func (*Repo) Component 

func (r *Repo) Component(repositoryID string) (domain.StackComponent, bool)

Component returns the stack component with the given repository ID.

func (*Repo) EnvironmentPath 

func (r *Repo) EnvironmentPath(name string) string

EnvironmentPath is the file an environment name maps to.

func (*Repo) GetEnvironment 

func (r *Repo) GetEnvironment(name string) (domain.Environment, error)

GetEnvironment loads one environment.

func (*Repo) GetRelease 

func (r *Repo) GetRelease(_ context.Context, name string) (domain.Release, error)

GetRelease implements controlplane.ControlPlane.

func (*Repo) GetTarget 

func (r *Repo) GetTarget(_ context.Context, name string) (domain.Target, error)

GetTarget implements controlplane.ControlPlane.

func (*Repo) HasMirror 

func (r *Repo) HasMirror(repositoryID string) bool

HasMirror reports whether a component has been fetched at least once.

func (*Repo) ListEnvironments 

func (r *Repo) ListEnvironments() ([]string, error)

ListEnvironments returns environment names in lexical order.

func (*Repo) ListReleases 

func (r *Repo) ListReleases() ([]string, error)

ListReleases returns release names in lexical order.

func (*Repo) ListTargets 

func (r *Repo) ListTargets() ([]string, error)

ListTargets returns target names in lexical order.

func (*Repo) MirrorPath 

func (r *Repo) MirrorPath(repositoryID string) (string, error)

MirrorPath returns the bare mirror directory for a component.

func (*Repo) Overrides 

func (r *Repo) Overrides() (*domain.ResourceOverrides, error)

Overrides loads resource-overrides.yaml; a missing file means no overrides.

func (*Repo) Path 

func (r *Repo) Path(parts ...string) string

Path returns an absolute path inside the coordination repository.

func (*Repo) Rel 

func (r *Repo) Rel(abs string) string

Rel returns a repository-relative slash path for display.

func (*Repo) ReleasePath 

func (r *Repo) ReleasePath(name string) string

ReleasePath is the file a release name maps to.

func (*Repo) RemoteHasRef 

func (r *Repo) RemoteHasRef(ctx context.Context, comp domain.StackComponent, commit string) (bool, error)

RemoteHasRef reports whether the component's Git remote still advertises a ref pointing at commit. Release creation uses it to warn that a pin is not reachable from a durable advertised ref.

func (*Repo) ResolveRef 

func (r *Repo) ResolveRef(ctx context.Context, repositoryID, ref string) (string, error)

ResolveRef resolves a branch, tag, or SHA in a component mirror to a full commit ID. A ref that does not exist locally is not silently fetched: the caller decides when the network is allowed.

func (*Repo) RuntimeResources 

func (r *Repo) RuntimeResources() (*domain.RuntimeResourceCatalog, error)

RuntimeResources loads runtime-resources.yaml; a missing file is an empty catalog, because a composition made only of component repositories is legitimate.

func (*Repo) SaveEnvironment 

func (r *Repo) SaveEnvironment(env domain.Environment) (string, error)

SaveEnvironment writes one environment record.

func (*Repo) SaveRuntimeResources 

func (r *Repo) SaveRuntimeResources(cat *domain.RuntimeResourceCatalog) error

SaveRuntimeResources writes runtime-resources.yaml.

func (*Repo) SaveStack 

func (r *Repo) SaveStack(ws *domain.Stack) error

SaveStack writes fxvcs.yaml after re-validating it.

func (*Repo) SaveTarget 

func (r *Repo) SaveTarget(t domain.Target) (string, error)

SaveTarget writes one target record.

func (*Repo) SetTargetRelease 

func (r *Repo) SetTargetRelease(ctx context.Context, target, release string) error

SetTargetRelease implements controlplane.ControlPlane. It edits desired state in the working tree; the change becomes authoritative only when a human or CI commits and pushes it.

func (*Repo) SyncComponent 

func (r *Repo) SyncComponent(ctx context.Context, comp domain.StackComponent) error

SyncComponent creates the mirror if needed and fetches all branches and tags from the component's remote. It is the only operation in this package that touches the network.

func (*Repo) TagComponent 

func (r *Repo) TagComponent(ctx context.Context, comp domain.StackComponent, tag, commit, message string) error

TagComponent creates an annotated tag in the component's remote naming the pinned commit. It is only reached through `release create --tag-components`, which plans every tag first and never accepts partial tagging as success.

func (*Repo) TargetPath 

func (r *Repo) TargetPath(name string) string

TargetPath is the file a target name maps to.

func (*Repo) Tree 

func (r *Repo) Tree(ctx context.Context, repositoryID, commit string) (*Tree, error)

Tree opens a pinned commit in a component mirror.

func (*Repo) WriteRelease 

func (r *Repo) WriteRelease(ctx context.Context, rel domain.Release) (path string, rewritten bool, err error)

WriteRelease writes a new release record. A release name is permanently bound to its content digest: writing over an existing record is refused unless the semantic content is identical, in which case the write is a no-op and rewritten reports false.

type Tree 

type Tree struct {
	RepositoryID string
	Commit       string
	// contains filtered or unexported fields
}

Tree reads one pinned component commit.

func (*Tree) CopyBlob 

func (t *Tree) CopyBlob(ctx context.Context, oid string, w io.Writer) error

CopyBlob streams one pinned blob without buffering it in memory.

func (*Tree) Entries 

func (t *Tree) Entries(ctx context.Context) ([]TreeEntry, error)

Entries lists every blob in the pinned tree, sorted by path.

func (*Tree) FS 

func (t *Tree) FS(ctx context.Context) (*FS, error)

FS builds the filesystem view of a pinned tree.

func (*Tree) ReadBlob 

func (t *Tree) ReadBlob(ctx context.Context, oid string) ([]byte, error)

ReadBlob returns the bytes of one object name from the pinned tree.

func (*Tree) ReadFile 

func (t *Tree) ReadFile(ctx context.Context, path string) ([]byte, error)

ReadFile returns the bytes of one path in the pinned tree. A missing path returns controlplane.ErrNotFound.

func (*Tree) RepositoryConfig 

func (t *Tree) RepositoryConfig(ctx context.Context) (*domain.Repository, error)

RepositoryConfig loads the component's committed .fxvcs/repository.yaml from the pinned tree. This is what makes a component self-describing: its accepted source root and layout travel with the commit, so composition never has to guess them.

func (*Tree) ResourceCatalog 

func (t *Tree) ResourceCatalog(ctx context.Context) (*domain.ResourceCatalog, error)

ResourceCatalog loads the component's committed .fxvcs/resources.yaml. A component with no catalog returns controlplane.ErrNotFound so the caller can say which repository needs `fxvcs resources sync`.

type TreeEntry 

type TreeEntry struct {
	// Path is the normalized repository-relative path.
	Path string
	// Mode is the Git file mode ("100644", "100755", "120000", "160000").
	Mode string
	// OID is the blob object name.
	OID string
	// Size is the blob size in bytes.
	Size int64
}

TreeEntry is one blob of a pinned component tree.

func (TreeEntry) IsRegular 

func (e TreeEntry) IsRegular() bool

IsRegular reports a mode an asset index may contain.

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.