gitsrv

package
v0.7.12-dev.2 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 44 Imported by: 0

Documentation

Overview

Package gitsrv implements git hosting: bare-repo storage keyed by repo UUID, smart HTTP v2 by shelling out to git, and the pre-receive policy hook.

Index

Constants

View Source
const KindRepoGC = "repo.gc"

KindRepoGC is the gc job: housekeeping for a bare repository after pushes. The git handler enqueues one per accepted push with a delay so a burst of pushes coalesces into a quiet moment, and the job runs `git gc --auto`, which is a no-op unless git's own thresholds (loose objects, pack count) say there is work — so an extra job costs a fork and nothing else.

View Source
const KindRepoPushed = "repo.pushed"

KindRepoPushed is the `repo.pushed` queue event. The git handler enqueues one per accepted push, in the request; the bookkeeping it carries — repo size, last_push_at, the audit row — then runs from the queue, so a git-role crash between receive-pack and bookkeeping does not lose them. Enqueue is one INSERT and is what makes the work durable; the handler keeps its inline path only for the no-queue case (tests, a role wired without a queue client).

Variables

This section is empty.

Functions

func RunPreReceiveHook

func RunPreReceiveHook(stdin io.Reader, stderr io.Writer) int

RunPreReceiveHook implements `agentryd hook pre-receive`. git runs it inside the bare repo with "old new ref" lines on stdin; the request context (pusher permissions, quotas) arrives via AGENTRY_HOOK_* env vars set by the serving process. Exit non-zero rejects the push; stderr lines reach the git client.

Enforced here (object-level checks are possible because git exposes the quarantined incoming objects to hooks):

  • v* tags: creation requires publish permission; updating or deleting an existing v* tag is always denied (immutable version namespace)
  • default branch: no deletion; no force-push unless allowed
  • new tips: no nested .git entries, no blobs over the size cap
  • repo quota: approximate disk usage check; over the warn tier the push succeeds and the pusher is told (git relays hook stderr as "remote:" lines)

Types

type Handler

type Handler struct {

	// PostReceive is invoked after a successful push with the updated refs
	// (the registry wires tag→submission here).
	PostReceive func(ctx context.Context, agent registry.Agent, refs []RefUpdate, pusher *auth.Principal)
	// contains filtered or unexported fields
}

Handler serves the git smart-HTTP surface: info/refs, git-upload-pack, git-receive-pack. Auth is PAT-only Basic; sessions are never accepted on git endpoints (CSRF hygiene).

func NewHandler

func NewHandler(cfg config.Config, st *store.Store, repos *RepoStore, reg *registry.Service, aud *audit.Writer, log *slog.Logger) *Handler

NewHandler assembles the git HTTP layer.

func (*Handler) Close

func (h *Handler) Close() error

Close releases the two bucket stores' collector goroutines.

func (*Handler) Mount

func (h *Handler) Mount(mux httpmux.Mux)

Mount registers the git routes on a mux (shared in `all`, alone in `git`). The mux is an interface so the api role can hand over one that records what it was given: that recording is what its authorization completeness gate reads, and these routes are not part of the OpenAPI surface the gate walks.

func (*Handler) NewSSHServer

func (h *Handler) NewSSHServer(addr, hostKeyFile string) (*SSHServer, error)

NewSSHServer builds the server listening on addr. hostKeyFile is the OpenSSH-format private key; an empty path means {dataDir}/ssh_host_ed25519_key, generated on first use.

func (*Handler) SetMetrics

func (h *Handler) SetMetrics(m *metrics.Metrics)

SetMetrics wires the git instrument set.

func (*Handler) SetQueue

func (h *Handler) SetQueue(q queue.Client)

SetQueue makes push bookkeeping a durable repo.pushed job.

type PushBookkeeper

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

PushBookkeeper performs the repo.pushed bookkeeping. repos may be nil on a role without repository storage: the size is then left as it was and only last_push_at advances (TouchRepoOnPush), exactly as when `du` fails.

func NewPushBookkeeper

func NewPushBookkeeper(st *store.Store, repos *RepoStore, aud *audit.Writer, log *slog.Logger) *PushBookkeeper

NewPushBookkeeper wires the bookkeeping for a role.

func (*PushBookkeeper) Register

func (b *PushBookkeeper) Register(q queue.Client)

Register attaches the repo.pushed handler to a queue client.

func (*PushBookkeeper) Run

Run does the bookkeeping for one push: size + last_push_at, then the audit row. A failed measurement degrades to a touch rather than a failed job (the refs are already durable; the size catches up on the next push), while a failed database write returns the error so the queue retries it.

type RefUpdate

type RefUpdate struct {
	Old, New, Ref string
}

RefUpdate is one receive-pack command (old, new, ref).

type RepoGCArgs

type RepoGCArgs struct {
	RepoID uuid.UUID `json:"repoId"`
}

RepoGCArgs is the job payload.

type RepoPushedArgs

type RepoPushedArgs struct {
	AgentID uuid.UUID `json:"agentId"`
	RepoID  uuid.UUID `json:"repoId"`
	// OrgID is the owning org for org-scoped audit; zero for user agents.
	OrgID uuid.UUID `json:"orgId,omitempty"`
	// ActorID is the pushing principal's user id (audit actor, PAT kind).
	ActorID uuid.UUID `json:"actorId"`
	// Refs are the accepted ref names, e.g. refs/heads/main, refs/tags/v1.0.0.
	Refs []string `json:"refs"`
}

RepoPushedArgs is the job payload. Everything the bookkeeping needs is carried so the worker never re-derives the principal or the agent.

type RepoStore

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

RepoStore manages bare repositories under cfg.Git.DataDir: {dataDir}/{uuid[0:2]}/{uuid}.git.

func NewRepoStore

func NewRepoStore(cfg config.Config) (*RepoStore, error)

NewRepoStore builds the store. hookBin is the agentryd binary the hooks exec; empty means the current executable.

func (*RepoStore) ArchiveCommit

func (s *RepoStore) ArchiveCommit(ctx context.Context, repoID uuid.UUID, commit string) (io.ReadCloser, error)

ArchiveCommit is ArchiveTag for a commit already resolved: the worker rebuilds a tag's archive from the commit the git role recorded, so a tag moved in between cannot change what is stored. The commit must be a full object id naming a commit in the repository.

func (*RepoStore) ArchiveTag

func (s *RepoStore) ArchiveTag(ctx context.Context, repoID uuid.UUID, tag string) (io.ReadCloser, string, error)

ArchiveTag implements the tar half of release publication: `git archive {tag}` from the bare repo — never a working-tree checkout, no hook execution, no gitattributes filtering. The tar is streamed to a temp file (a release tree may be as large as the repo quota; buffering it in RAM would let a push size the server's heap) and the returned ReadCloser removes that file on Close. The second return value is the peeled commit id.

func (*RepoStore) Command

func (s *RepoStore) Command(ctx context.Context, service string, args ...string) (cmd *exec.Cmd, done func(), err error)

Command starts a git service (upload-pack, receive-pack) for a client; done must be called once git has exited. A receive-pack gets its own hooks directory (pushHooks) as core.hooksPath, given on the command line, where it outranks any repository or environment config; when no hook will run, no receive-pack is started and the error says why.

func (*RepoStore) CommitFork

func (s *RepoStore) CommitFork(ctx context.Context, repoID uuid.UUID, c registry.ForkCommit) (string, error)

CommitFork writes the fork's commit and points c.Refs at it. The tree is built in a private index: c.BaseCommit's tree read into it, or c.Dir's files hashed into it one by one, then c.Manifest written over c.ManifestPath. c.Dir is an uploaded release's archive, so git never looks at it as a work tree: no `git add`, which would honour a .gitattributes among its files, read a .gitignore, and follow a `.git` file to whatever repository on this host it names (recording that repository's HEAD as a gitlink). Each file is hashed with --no-filters by its own path, and a path with a `.git` component is refused outright.

func (*RepoStore) CopyHistory

func (s *RepoStore) CopyHistory(ctx context.Context, src, dst uuid.UUID, defaultBranch, commit string) error

CopyHistory creates dst on defaultBranch and copies into it commit and its history from src, and nothing else: no other branch or tag, and no object only they reach. The commit is fetched through a tag of src that points at it, the same tags a reader with no role may clone, so a commit no tag names is not copied and dst stays empty. git serves any object of a repository to a client that names its id, so whoever owns dst can read all of it; it must hold only what they could read of src. A fetch from a local path copies the objects into dst's own packs, never alternates or hard links, so deleting, retiring or rewriting the origin later leaves the fork as it was. An origin that was never pushed to has no repository on disk, and dst stays empty.

func (*RepoStore) DiskUsage

func (s *RepoStore) DiskUsage(repoID uuid.UUID) (int64, error)

DiskUsage returns the repo's approximate size in bytes.

func (*RepoStore) EnsureBare

func (s *RepoStore) EnsureBare(ctx context.Context, repoID uuid.UUID, defaultBranch string) error

EnsureBare makes the repository if it is not there yet. A repository that exists, or that a concurrent call made first, is success.

func (*RepoStore) GC

func (s *RepoStore) GC(ctx context.Context, repoID uuid.UUID) error

GC runs git's automatic housekeeping on a bare repository, bounded in time and with the same neutral environment archive/hook execution uses.

func (*RepoStore) HasCommit

func (s *RepoStore) HasCommit(ctx context.Context, repoID uuid.UUID, commit string) (bool, error)

HasCommit reports whether commit is a commit in the repository. What it and ReadFileAt are given comes from a version row, and is checked as an object id anyway before it reaches git's argument list.

func (*RepoStore) HistoryPatch

func (s *RepoStore) HistoryPatch(ctx context.Context, repoID uuid.UUID, commit string) (io.ReadCloser, error)

HistoryPatch streams the added lines of every non-merge commit reachable from commit as a unified diff (S2 scans full git history on git-tag publishes). The stream is `git log -p` with each commit introduced by a line of the form "\x01<sha>" so the consumer can attribute a hit without ambiguity, zero context lines, no renames, and binary hunks summarized. Closing the reader terminates git.

func (*RepoStore) InitBare

func (s *RepoStore) InitBare(ctx context.Context, repoID uuid.UUID, defaultBranch string) error

InitBare creates and configures a bare repository: default branch, deny-delete-current, quota-derived receive.maxInputSize, policy hooks. The repository is built in a private directory beside its final path and renamed into place, so it appears complete or not at all. Of concurrent calls for one repository, one succeeds and the others get errRepoExists.

func (*RepoStore) MaterializeCommit

func (s *RepoStore) MaterializeCommit(ctx context.Context, repoID uuid.UUID, commit, dst string) error

MaterializeCommit implements registry.GitArchiver: extracts `git archive {commit}` into dst, as MaterializeTag does for a tag.

func (*RepoStore) MaterializeTag

func (s *RepoStore) MaterializeTag(ctx context.Context, repoID uuid.UUID, tag, dst string) (commitSHA string, err error)

MaterializeTag implements registry.GitArchiver: extracts `git archive {tag}` into dst (plain tar, produced by our own git — still extracted defensively) and returns the peeled commit id.

func (*RepoStore) Path

func (s *RepoStore) Path(repoID uuid.UUID) string

Path returns the bare-repo directory for a repo id.

func (*RepoStore) PrepareHooks

func (s *RepoStore) PrepareHooks() error

PrepareHooks proves the git role can run its pre-receive hook: it makes a hooks directory the way every push does (pushHooks), runs the hook there, and removes it. The git role calls it at startup, so a hooks base that cannot run hooks (a noexec mount) stops the role instead of every push being refused.

Git runs the hook from such a directory rather than from each bare repository's hooks/ because the repository volume may be one the kernel will not exec from: on a virtiofs file system, for example, git fails with "cannot exec 'hooks/pre-receive': Bad address".

func (*RepoStore) ReadFileAt

func (s *RepoStore) ReadFileAt(ctx context.Context, repoID uuid.UUID, commit, path string) ([]byte, error)

ReadFileAt reads the blob at path in commit. A path the commit does not hold is fs.ErrNotExist, which trying again does not change.

func (*RepoStore) RefsAt

func (s *RepoStore) RefsAt(ctx context.Context, repoID uuid.UUID, refs []string) (map[string]string, error)

RefsAt reads the current object id of each named ref, omitting refs that do not exist. Push bookkeeping uses it to tell which requested updates were actually applied: receive-pack exits 0 even when the pre-receive hook rejects every command, so the repository — not the request — is the authority on what changed. A name that is not a plain ref is never looked up and never in the result; nil refs lists every ref.

func (*RepoStore) Remove

func (s *RepoStore) Remove(repoID uuid.UUID) error

Remove deletes a bare repository (compensation path).

func (*RepoStore) RemoveRepository

func (s *RepoStore) RemoveRepository(repoID uuid.UUID) error

RemoveRepository deletes a repository a failed copy left behind; one that is not there is nothing to remove.

func (*RepoStore) ReviewedView

func (s *RepoStore) ReviewedView(ctx context.Context, repoID uuid.UUID, tags map[string]string, head string) (string, error)

ReviewedView returns a bare repository that holds the given tags (full ref name → the tag's object id) and only the objects they reach, with HEAD detached at head. It is what a reader is served when they may read only what passed review: git serves any object of a repository to a client that names its id, so the only sure way to keep the rest from them is a repository without it. A view is built once for its set of tags and kept, under {dataDir}/views, until the set changes; older views of the same repository are removed once none has been used for viewStaleAfter.

func (*RepoStore) SweepInitLeftovers

func (s *RepoStore) SweepInitLeftovers() (int, error)

SweepInitLeftovers removes the work directories InitBare leaves beside a repository's final path ({dataDir}/{xx}/.{uuid}.git.init-*) when the process dies before it cleans up, once they are older than initWorkStaleAfter. Nothing reads such a directory, so without the sweep they only accumulate on the repository volume. It touches nothing whose name is not exactly that form, and returns how many it removed.

func (*RepoStore) SweepViewLeftovers

func (s *RepoStore) SweepViewLeftovers() (int, error)

SweepViewLeftovers removes the work directories ReviewedView leaves under {dataDir}/views/{xx}/{uuid}-build-* when the process dies before it renames or removes them, once they are older than viewBuildStaleAfter. pruneViews matches only finished views, so without the sweep these only accumulate on the repository volume. It touches nothing whose name is not exactly that form, and returns how many it removed.

func (*RepoStore) Tags

func (s *RepoStore) Tags(ctx context.Context, repoID uuid.UUID) (map[string]Tag, error)

Tags lists the repository's tags by full ref name. A tag that does not point at a commit is left out. A repository never pushed to has none.

type SSHServer

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

SSHServer serves git over SSH for one Handler.

func (*SSHServer) Addr

func (s *SSHServer) Addr() net.Addr

Addr is the bound listener address (tests use it for a random port).

func (*SSHServer) Close

func (s *SSHServer) Close() error

Close stops accepting and waits for in-flight sessions.

func (*SSHServer) HostKeyFingerprint

func (s *SSHServer) HostKeyFingerprint() string

HostKeyFingerprint is the SHA256 fingerprint operators publish for known_hosts pinning.

func (*SSHServer) Serve

func (s *SSHServer) Serve(ctx context.Context) error

Serve accepts connections until ctx ends or Close is called.

type Tag

type Tag struct {
	Object string
	Commit string
}

Tag is a tag's own object id and the commit it points at: the same id for a lightweight tag, the commit an annotated tag peels to otherwise.

Jump to

Keyboard shortcuts

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