gitlimit

package
v0.20.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

README

internal/gitlimit

Overview

Shared admission and process control for git subprocesses. It provides a slot pool that bounds concurrent git reads and maintenance, a registry that starts, reaps, and stops git child process groups, and a per-child heap cap on Linux through ulimit -d.

Interface

  • HeavyHeapBytes (256 MiB), ReadSlotCount (8), RepoSlotCount (2), ReadSlotWait (1 s), MaintenanceShare (2) — sizing constants [gitlimit.go:HeavyHeapBytes]
  • ErrBusy, ErrMemoryLimit — no slot in time, and git stopped by its own allocation failure [gitlimit.go:ErrBusy]
  • Slots, NewSlots, (*Slots).Acquire, TryAcquire, Release, InUse — slot pool with a per-key cap [gitlimit.go:Slots]
  • RepoKey — per-repository slot key from a canonical repo ID [gitlimit.go:RepoKey]
  • ReadSlots — process-wide pool shared by JSON git reads and admitted maintenance [gitlimit.go:ReadSlots]
  • TryAdmitMaintenance — non-blocking admission of one maintenance job; returns a release func [gitlimit.go:TryAdmitMaintenance]
  • ErrStopping, Start, Wait, Run, Output, Stopping, StopChildren — tracked git child lifecycle [children.go:Start]
  • LeaseFile, LeaseFD (10), ErrLeaseBusy, OpenLease(ctx, repo), TryExclusive, (*Lease).Attach, Close, StartIn, RunIn, OutputIn, CombinedOutputIn (each takes ctx first) — the shared lease that every git child in a cache repository holds as its descriptor LeaseFD, so that an exclusive lock proves no git that serve started is alive there (#490) [lease.go:LeaseFile] [lease.go:StartIn]
  • NoReplaceObjects — an environment with GIT_NO_REPLACE_OBJECTS=1, for a git child that does not go through Start [children.go:NoReplaceObjects]
  • Name, Clip — a git command line, and one value, for an error message or a log line: a value is cut at 256 bytes and its length is named, and at most 32 arguments are printed [name.go:Name] [name.go:Clip]
  • TailBuffer — the stderr tail that an error quotes: the last 64 KiB, where git prints its fatal message [errtext.go:TailBuffer]
  • HeadBuffer — the output head that a reason quotes: the first 64 KiB, for a command that prints its reason first, with the count of dropped bytes [errtext.go:HeadBuffer]
  • HeapLimitSupported, Command, HeapFailure — heap cap support (Linux: /bin/sh wrapper with ulimit -d; other platforms: no cap) and heap-failure classification [heaplimit_linux.go:Command] [heaplimit_other.go:Command]

Invariants

  • TailBuffer keeps the last 64 KiB written to it and holds at most twice that much memory, also after one large Write; small writes cost time linear in their size; a tail that was cut starts at a UTF-8 character [errtext.go:TailBuffer]
  • HeadBuffer keeps the first 64 KiB written to it and counts the rest in Dropped [errtext.go:HeadBuffer]
  • CombinedOutputIn returns only the last 64 KiB of the child's combined output, kept by a TailBuffer [lease.go:CombinedOutputIn] [lease_test.go:TestCombinedOutputInKeepsTheLast64KiB]
  • NewSlots panics unless n > 0, 0 < perKey <= n, and wait >= 0 [gitlimit.go:NewSlots]
  • Release panics unless the key holds a slot; RepoKey panics on an empty repo ID [gitlimit.go:Release]
  • TryAdmitMaintenance takes the maintenance permit first, releases it if ReadSlots is full, and panics on a second release call [gitlimit.go:TryAdmitMaintenance]
  • Acquire with wait 0 returns ErrBusy at once when no slot is free [gitlimit.go:Acquire]
  • Output panics if the caller already set Stdout [children.go:Output]
  • registry.start panics if SysProcAttr is already set, forces Setpgid, sets GIT_NO_REPLACE_OBJECTS=1 so that git reads every object as itself (any token with git:write can push refs/replace/*), and refuses new children with ErrStopping after stop began [children.go:start]
  • registry.stop sends SIGTERM before SIGKILL so git can clean its lock files [children.go:stop]
  • stop signals only groups it finds registered while it holds the registry lock, and on Linux wait removes a group from the registry before it reaps the leader, so a signal reaches a group whose leader still owns its ID and never one whose ID the kernel recycled (#473) [children.go:wait] [children.go:stop]
  • On Linux a leader that exits after stop began stays an unreaped zombie until stop has sent its final SIGKILL, which still ends a member the leader left behind. awaitExit waits for the exit with waitid(WNOWAIT). A member left behind by a leader that exited before stop began is out of reach: its group left the registry at the exit, and a member that keeps the child's output pipe open keeps Wait blocked until it exits [children.go:wait] [exit_linux.go:awaitExit]
  • Platforms other than Linux use a reap-first wait. macOS has no wait that leaves the child unreaped: Go's os package does not use waitid there because it also returns for a stopped child (golang/go#19314). FreeBSD and NetBSD have wait6, which this package does not use because releases build only linux and darwin. wait reaps first and removes the group right after. stop sends no signal, SIGTERM or SIGKILL, to a group that is not registered or whose leader os reports reaped. A leader that exits during the grace gets no final SIGKILL there, so a member it left behind is not killed. What stays open is the race that os.Process.Signal has on macOS (golang/go#13987): the leader is reaped between the check and the kill [children.go:wait] [children.go:signal] [exit_other.go:awaitExit]
  • A git child that runs in a cache repository starts through StartIn, RunIn, OutputIn or CombinedOutputIn, or attaches a Lease itself, and a plain Start takes no lease. TestEveryGitStartTakesTheLease fails on a git start in the module that does neither and is not listed with a reason, and on a new file that imports os/exec until the file is listed in execImporters. TestAuditSeesEveryWayToBuildGit proves each way it recognizes to build git: exec.Command, an exec.Cmd literal, exec.Command held as a value, any program that is not in nonGitPrograms (a launcher can start git), os.StartProcess and syscall.Exec, a dot import, and a package-level initializer. TestAuditChecksTheAllowLists pins the stale-entry and unlisted-file checks. A binary built with the openstorage_viewcheck tag panics on a plain start that has a Dir or an argument that is a repository path, and on a leased start that runs in another repository [lease_audit_test.go:TestEveryGitStartTakesTheLease] [lease_audit_test.go:TestAuditSeesEveryWayToBuildGit] [lease_audit_test.go:TestAuditChecksTheAllowLists] [leasecheck_viewcheck.go:init]
  • OpenLease creates LeaseFile when it is missing and never removes it. It waits up to 30 s while the lease is held exclusively, then fails with ErrLeaseBusy. The wait ends at once with ctx's error when ctx ends, and with ErrStopping once StopChildren began. TryExclusive never waits [lease.go:OpenLease] [lease.go:TryExclusive] [lease_test.go:TestOpenLeaseStopsWaitingWhenChildrenAreStopping] [lease_test.go:TestOpenLeaseGivesUpAfterTheLeaseWait]
  • Leases are shared: any number coexist, and Attach panics on an exclusive one. The file has mode 0600 [lease.go:Attach] [lease_test.go:TestSharedLeasesCoexist] [lease_test.go:TestAttachRefusesAnExclusiveLease] [lease_test.go:TestLeaseFileIsPrivate]
  • Only a read-only filesystem (EROFS) changes OpenLease: nothing can write a ref lock there, so reads must still run. An existing lease file is opened read-only and locked, which flock allows, so the lease is a real one. With no lease file, the lease holds nothing and Attach adds no descriptor. Any other failure is an error, a permission error included: a directory that serve cannot write can still have a writable refs/, where a git without the lease could take ref locks [lease.go:OpenLease] [lease_test.go:TestReadOnlyFilesystemWithALeaseFileHoldsARealLease] [lease_test.go:TestReadOnlyFilesystemWithoutALeaseFileStillRuns] [lease_test.go:TestReadOnlyFilesystemWithAnUnreadableLeaseFileFails] [lease_test.go:TestOpenLeaseFailsClosedOutsideAReadOnlyFilesystem]
  • A start that fails before the child runs, because the lease cannot be taken or StopChildren began, closes the pipes that the caller made with StdinPipe and StdoutPipe [children.go:failStart] [lease_test.go:TestStartInClosesThePipesOfAStartThatFails]
  • The lock lives as long as the child's process tree: the parent closes its copy after Start, and the child, its hooks and their children keep descriptor LeaseFD. Descriptors 3 to 9 are closed in the child, because Git writes GIT_TRACE=3 to descriptor 3 [lease.go:Attach] [lease_test.go:TestGitTraceToADescriptorBelowTenNeverReachesTheLease]. A start that fails releases it at once [lease.go:StartIn] [lease_test.go:TestLeaseLivesWithTheGitProcessTree] [lease_test.go:TestFailedStartReleasesTheLease]
  • The Linux wrapper keeps a stricter inherited soft limit and exits 125 if it cannot read or set the limit [heaplimit_linux.go:heapLimitWrapper]
  • HeapFailure ignores SIGKILL and matches git diagnostics only at line start [heaplimit_linux.go:HeapFailure]
  • Non-Linux Command asserts maxHeapBytes == 0 [heaplimit_other.go:Command]

Side Effects

  • Starts git children (through /bin/sh when a heap cap is set), each as its own process group [children.go:start]
  • Sends SIGTERM then SIGKILL to tracked groups in StopChildren, polling every 10 ms until every leader has exited or the grace deadline [children.go:stop]
  • Blocks one goroutine per child until its leader exits: in waitid(WNOWAIT) before it reaps on Linux, in Wait elsewhere [exit_linux.go:awaitExit] [exit_other.go:awaitExit]
  • Holds mutexes on slot state and on the child registry; release closes and replaces the freed channel to wake waiters [gitlimit.go:Release]
  • Output buffers child output in memory [children.go:Output]
  • OpenLease and TryExclusive create and lock <repo>/codestorage.gitlease.lock [lease.go:OpenLease]

Verification

  • Run: go test ./internal/gitlimit/... -tags=openstorage_viewcheck -count=1 -race -timeout=30m

Documentation

Overview

Package gitlimit is the shared chokepoint for git subprocesses that untrusted input can make expensive (#313, #322): the process-wide admission pool, the per-child heap cap, and their error values. The read API (internal/gitread, ADR-049) and cache maintenance (internal/githttp's commit-graph refresh, ADR-47) both use it, so they share one admission pool instead of each bounding itself. It also tracks serve's git children for the shutdown stop (children.go). It is a leaf package: gitread imports githttp, so the shared pieces cannot live in gitread.

Index

Constants

View Source
const (
	// HeavyHeapBytes caps the heap (RLIMIT_DATA, Linux) of a child whose
	// work grows with history length, tree size, blob size, or output
	// size. See gitread.HeavyHeapBytes for the measurements.
	HeavyHeapBytes int64 = 256 << 20

	// ReadSlotCount is the size of ReadSlots: requests with JSON
	// responses that run git, plus admitted maintenance, at once in this
	// process.
	ReadSlotCount = 8
	// RepoSlotCount is how many slots of a pool one repository may hold.
	RepoSlotCount = 2
	// ReadSlotWait is how long a read request waits for a ReadSlots slot.
	ReadSlotWait = time.Second
	// MaintenanceShare is how many ReadSlots slots optional maintenance
	// (commit-graph refreshes) may hold at once, so it can never take the
	// whole pool from reads.
	MaintenanceShare = 2
)
View Source
const LeaseFD = 10

LeaseFD is the descriptor a git child holds the lease on. Git reads the descriptors 2 to 9 as trace targets (GIT_TRACE=3 writes to descriptor 3), so the lease sits above them, and the descriptors 3 to LeaseFD-1 are closed in the child.

View Source
const LeaseFile = "codestorage.gitlease.lock"

LeaseFile is the name of a cache repository's lease file, <repo>/LeaseFile (issue #490). Every git child that serve starts in a cache repository holds a shared flock on it, as its inherited file descriptor LeaseFD, for as long as the child's process tree lives: git, its hooks and their children all keep the descriptor. So winning the lock exclusively (TryExclusive) proves that no git that serve started for the repository is alive, and none can own one of its ref locks. The kernel arbitrates the lock across users, PID namespaces and containers on the same host, and an orphan of a crashed serve keeps holding it. The file is never removed.

Coverage is the whole proof: a git child in a cache repository that was started without the lease can own a ref lock that cleanup then removes. So every such child starts through StartIn, RunIn, OutputIn or CombinedOutputIn, or attaches a Lease itself (Lease.Attach). The audit test in this package fails on a new git start that does neither, and a binary built with the openstorage_viewcheck tag panics on a start that runs in a repository without a lease. Git that serve did not start holds no lease, so operators must not run it in a cache repository while serve runs, and must not reassign descriptor LeaseFD in a hook. The release that first takes the lease exclusively (the stale ref lock cleanup of #490) writes those rules into docs/how-to/deploy-production.md.

Variables

View Source
var (
	// ErrBusy: no admission slot freed up in time; git was not started.
	ErrBusy = errors.New("git read capacity exhausted")
	// ErrMemoryLimit: git needed more heap than its cap and was stopped by
	// its own allocation failure (Linux only).
	ErrMemoryLimit = errors.New("git exceeded its memory limit")
)
View Source
var ErrLeaseBusy = errors.New("git lease is busy")

ErrLeaseBusy: the lease is held exclusively (or, for TryExclusive, shared).

View Source
var ErrStopping = errors.New("server is shutting down")

ErrStopping refuses a git child started after StopChildren began.

ReadSlots is the process-wide pool shared by JSON git reads (the read API's budget middleware) and admitted maintenance.

Functions

func Clip added in v0.20.0

func Clip(s string) string

Clip bounds a value that goes into an error message or a log line. A value of at most maxNameArgBytes is returned as it is. A longer one is cut at maxNameArgBytes, at a character boundary, and followed by its length.

func CombinedOutputIn added in v0.20.0

func CombinedOutputIn(ctx context.Context, repoPath string, cmd *exec.Cmd) ([]byte, error)

CombinedOutputIn is exec.Cmd.CombinedOutput through the registry and the lease of the repository at repoPath, but it returns only the last 64 KiB of the output (TailBuffer), so that an error or a log line that quotes it stays bounded however much git prints. Stdout and Stderr are one writer, so exec calls its Write from one goroutine at a time.

func Command

func Command(ctx context.Context, maxHeapBytes int64, args ...string) *exec.Cmd

Command returns `git args...`. When maxHeapBytes > 0 it runs git behind /bin/sh, which sets RLIMIT_DATA (`ulimit -d`, KiB) and then execs git, so the limit is in force before git allocates anything and the process id stays git's (context kill and Wait still reach git). An inherited stricter limit is kept. If the limit cannot be read or set, the shell exits 125 and git never runs.

RLIMIT_DATA counts the heap and other private writable mappings, which includes every thread's stack and malloc arena; read-only pack mappings (shared page cache) are not counted.

func HeapFailure

func HeapFailure(waitErr error, stderr string) bool

HeapFailure reports whether a git run under a heap cap died of it: git's fatal allocation diagnostics, or, when the cap is hit before or outside git's checked allocators (dynamic loader, libc), a crash by SIGSEGV, SIGBUS, or SIGABRT. SIGKILL (context cancellation or deadline) is not a heap failure.

Only a fatal line that STARTS with a known diagnostic counts: git messages can quote request input (a path named "out of memory"), and such text never forms the start of the line.

func HeapLimitSupported

func HeapLimitSupported() bool

HeapLimitSupported reports whether Run can cap a git child's heap on this platform (RLIMIT_DATA via `ulimit -d`).

func Name added in v0.20.0

func Name(args []string) string

Name renders a git command line for an error message, and so for a log line. A request can put a value of 100 KB or more into an argument (a path, a pattern), and a command can carry any number of them. Name clips each argument (see Clip). It prints at most maxNameArgs arguments and counts the rest. A command line within both limits is printed as it is.

func NoReplaceObjects added in v0.20.0

func NoReplaceObjects(env []string) []string

NoReplaceObjects returns env (nil: the server's environment) with GIT_NO_REPLACE_OBJECTS set, so that git reads every object as itself. Any token with git:write can push refs/replace/<id>, which would otherwise make git read one object as another: a commit with other parents in a no-force-push check, a signed commit in a verify-sig check, another tree under a server-written commit. Every child that Start runs gets it, and receive-pack passes it to its hooks.

func Output added in v0.19.0

func Output(cmd *exec.Cmd) ([]byte, error)

Output is exec.Cmd.Output through the registry. cmd.Stdout must be nil.

func OutputIn added in v0.20.0

func OutputIn(ctx context.Context, repoPath string, cmd *exec.Cmd) ([]byte, error)

OutputIn is exec.Cmd.Output through the registry and the lease of the repository at repoPath. cmd.Stdout must be nil.

func RepoKey

func RepoKey(repoID string) string

RepoKey is the Slots key of a repository: its canonical RepoID, so every spelling of one repository shares one per-repository quota.

func Run added in v0.19.0

func Run(cmd *exec.Cmd) error

Run is Start followed by Wait.

func RunIn added in v0.20.0

func RunIn(ctx context.Context, repoPath string, cmd *exec.Cmd) error

RunIn is StartIn followed by Wait.

func Start added in v0.19.0

func Start(cmd *exec.Cmd) error

Start starts cmd as the leader of a new process group and tracks it. A git that runs in a cache repository starts through StartIn instead (lease.go).

func StartIn added in v0.20.0

func StartIn(ctx context.Context, repoPath string, cmd *exec.Cmd) error

StartIn is Start for a git child that runs in the cache repository at repoPath: cmd inherits a shared lease as descriptor LeaseFD (see LeaseFile). ctx bounds the wait for the lease (see OpenLease), not the child.

func StopChildren added in v0.19.0

func StopChildren(grace time.Duration) int

StopChildren ends every tracked git child and refuses new ones: serve calls it when the shutdown drain times out, so no tracked child outlives serve. It sends SIGTERM to each child's process group, waits up to grace for the leaders to exit, then sends SIGKILL to those groups. It returns the number of groups it signaled.

func Stopping added in v0.19.0

func Stopping() bool

Stopping reports whether StopChildren began.

func TryAdmitMaintenance

func TryAdmitMaintenance(key string) (release func(), ok bool)

TryAdmitMaintenance admits one optional maintenance job for the repository key (RepoKey) into ReadSlots without waiting: it needs one of the MaintenanceShare maintenance permits AND one ReadSlots slot within that repository's share, both taken with non-blocking tries (no check-then-act on counts). So at most MaintenanceShare jobs run, reads always keep the rest of the pool, and a repository's maintenance and reads share its per-repository quota. ok=false means skip the job; a caller holding other locks never blocks here. release must be called exactly once when ok.

func Wait added in v0.19.0

func Wait(cmd *exec.Cmd) error

Wait waits for a child that Start started and stops tracking its group.

Types

type HeadBuffer added in v0.20.0

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

HeadBuffer is an output sink that keeps only the first 64 KiB written to it, for a command whose reason comes first, and counts the bytes it drops after that.

func (*HeadBuffer) Bytes added in v0.20.0

func (h *HeadBuffer) Bytes() []byte

Bytes returns the kept head.

func (*HeadBuffer) Dropped added in v0.20.0

func (h *HeadBuffer) Dropped() int64

Dropped returns the count of bytes written past the kept head.

func (*HeadBuffer) Write added in v0.20.0

func (h *HeadBuffer) Write(p []byte) (int, error)

type Lease added in v0.20.0

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

Lease is an open lease file with a flock on it. Close releases the lock unless a child that inherited the descriptor still holds it.

func OpenLease added in v0.20.0

func OpenLease(ctx context.Context, repoPath string) (*Lease, error)

OpenLease takes a shared lease on the repository at repoPath, creating the lease file if it is missing. It waits (bounded) while the lease is held exclusively. It fails with ctx's error once ctx ends, with ErrStopping once StopChildren began, and with ErrLeaseBusy if the wait does not end.

On a read-only filesystem (EROFS) nothing can write a ref lock, so a read there must still run. An existing lease file is opened read-only and locked, because flock needs no write access. With no lease file, the lease holds nothing and Attach adds no descriptor. Any other failure, a permission error included, is an error: a directory that serve cannot write can still have a writable refs/, where a git without the lease could take ref locks.

func TryExclusive added in v0.20.0

func TryExclusive(repoPath string) (*Lease, error)

TryExclusive takes the lease exclusively without waiting. It succeeds only when no process holds the lease, shared or exclusive: no git that serve started for the repository is alive. Until Close, StartIn and OpenLease wait. It returns ErrLeaseBusy when the lease is held.

func (*Lease) Attach added in v0.20.0

func (l *Lease) Attach(cmd *exec.Cmd)

Attach hands the lease to cmd as its descriptor LeaseFD. The caller starts cmd itself and closes the Lease after Start: the child keeps its own copy, so the lock lives exactly as long as the child's process tree. A Lease may be attached to several commands.

func (*Lease) Close added in v0.20.0

func (l *Lease) Close() error

Close closes the parent's copy of the lease file.

type Slots

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

Slots is a pool of admission slots. One key (a repository, RepoKey) may hold at most perKey of them, so slow work on one repository cannot take the whole pool from the others. A holder releases exactly the slots it acquired, under the same key.

func NewSlots

func NewSlots(n, perKey int, wait time.Duration) *Slots

NewSlots returns a pool of n slots, at most perKey of them per key. Acquire waits at most wait for a free slot before failing with ErrBusy.

func (*Slots) Acquire

func (s *Slots) Acquire(ctx context.Context, key string) error

Acquire takes a slot for key, waiting at most the pool's wait (ErrBusy) or until ctx ends (its error).

func (*Slots) InUse

func (s *Slots) InUse() int

InUse reports how many slots are held (tests and diagnostics).

func (*Slots) Release

func (s *Slots) Release(key string)

Release returns one slot taken for key.

func (*Slots) TryAcquire

func (s *Slots) TryAcquire(key string) bool

TryAcquire takes a slot for key if one is free right now.

type TailBuffer added in v0.20.0

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

TailBuffer is a stderr sink that keeps only the last 64 KiB written to it: git prints its fatal message last, and the rest must not grow an error (and the log record that quotes it) without bound. It holds at most twice that much memory, however much is written, also in one Write, and it copies each written byte a bounded number of times: git writes stderr a message at a time, and a slow git gives one pipe read per line.

func (*TailBuffer) String added in v0.20.0

func (t *TailBuffer) String() string

String returns the kept tail without surrounding white space. A tail that was cut starts at a character: the cut can land inside a UTF-8 sequence, and its continuation bytes are dropped.

func (*TailBuffer) Write added in v0.20.0

func (t *TailBuffer) Write(p []byte) (int, error)

Jump to

Keyboard shortcuts

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