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
- func RunPreReceiveHook(stdin io.Reader, stderr io.Writer) int
- type Handler
- type PushBookkeeper
- type RefUpdate
- type RepoGCArgs
- type RepoPushedArgs
- type RepoStore
- func (s *RepoStore) ArchiveCommit(ctx context.Context, repoID uuid.UUID, commit string) (io.ReadCloser, error)
- func (s *RepoStore) ArchiveTag(ctx context.Context, repoID uuid.UUID, tag string) (io.ReadCloser, string, error)
- func (s *RepoStore) Command(ctx context.Context, service string, args ...string) (cmd *exec.Cmd, done func(), err error)
- func (s *RepoStore) CommitFork(ctx context.Context, repoID uuid.UUID, c registry.ForkCommit) (string, error)
- func (s *RepoStore) CopyHistory(ctx context.Context, src, dst uuid.UUID, defaultBranch, commit string) error
- func (s *RepoStore) DiskUsage(repoID uuid.UUID) (int64, error)
- func (s *RepoStore) EnsureBare(ctx context.Context, repoID uuid.UUID, defaultBranch string) error
- func (s *RepoStore) GC(ctx context.Context, repoID uuid.UUID) error
- func (s *RepoStore) HasCommit(ctx context.Context, repoID uuid.UUID, commit string) (bool, error)
- func (s *RepoStore) HistoryPatch(ctx context.Context, repoID uuid.UUID, commit string) (io.ReadCloser, error)
- func (s *RepoStore) InitBare(ctx context.Context, repoID uuid.UUID, defaultBranch string) error
- func (s *RepoStore) MaterializeCommit(ctx context.Context, repoID uuid.UUID, commit, dst string) error
- func (s *RepoStore) MaterializeTag(ctx context.Context, repoID uuid.UUID, tag, dst string) (commitSHA string, err error)
- func (s *RepoStore) Path(repoID uuid.UUID) string
- func (s *RepoStore) PrepareHooks() error
- func (s *RepoStore) ReadFileAt(ctx context.Context, repoID uuid.UUID, commit, path string) ([]byte, error)
- func (s *RepoStore) RefsAt(ctx context.Context, repoID uuid.UUID, refs []string) (map[string]string, error)
- func (s *RepoStore) Remove(repoID uuid.UUID) error
- func (s *RepoStore) RemoveRepository(repoID uuid.UUID) error
- func (s *RepoStore) ReviewedView(ctx context.Context, repoID uuid.UUID, tags map[string]string, head string) (string, error)
- func (s *RepoStore) SweepInitLeftovers() (int, error)
- func (s *RepoStore) SweepViewLeftovers() (int, error)
- func (s *RepoStore) Tags(ctx context.Context, repoID uuid.UUID) (map[string]Tag, error)
- type SSHServer
- type Tag
Constants ¶
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.
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 ¶
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) Mount ¶
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 ¶
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 ¶
SetMetrics wires the git instrument set.
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 ¶
func (b *PushBookkeeper) Run(ctx context.Context, args RepoPushedArgs) error
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 ¶
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 ¶
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) EnsureBare ¶
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 ¶
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 ¶
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 ¶
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) PrepareHooks ¶
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) RemoveRepository ¶
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 ¶
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 ¶
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.
type SSHServer ¶
type SSHServer struct {
// contains filtered or unexported fields
}
SSHServer serves git over SSH for one Handler.
func (*SSHServer) HostKeyFingerprint ¶
HostKeyFingerprint is the SHA256 fingerprint operators publish for known_hosts pinning.