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
- Variables
- func CombinedOutput(cmd *exec.Cmd) ([]byte, error)
- func Command(ctx context.Context, maxHeapBytes int64, args ...string) *exec.Cmd
- func HeapFailure(waitErr error, stderr string) bool
- func HeapLimitSupported() bool
- func Output(cmd *exec.Cmd) ([]byte, error)
- func RepoKey(repoID string) string
- func Run(cmd *exec.Cmd) error
- func Start(cmd *exec.Cmd) error
- func StopChildren(grace time.Duration) int
- func Stopping() bool
- func TryAdmitMaintenance(key string) (release func(), ok bool)
- func Wait(cmd *exec.Cmd) error
- type Slots
Constants ¶
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 // (commit-graph refreshes) may hold at once, so it can never take the // whole pool from reads. MaintenanceShare = 2 )
Variables ¶
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") )
var ErrStopping = errors.New("server is shutting down")
ErrStopping refuses a git child started after StopChildren began.
var ReadSlots = NewSlots(ReadSlotCount, RepoSlotCount, ReadSlotWait)
ReadSlots is the process-wide pool shared by JSON git reads (the read API's budget middleware) and admitted maintenance.
Functions ¶
func CombinedOutput ¶ added in v0.19.0
CombinedOutput is exec.Cmd.CombinedOutput through the registry.
func Command ¶
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 ¶
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 Output ¶ added in v0.19.0
Output is exec.Cmd.Output through the registry. cmd.Stdout must be nil.
func RepoKey ¶
RepoKey is the Slots key of a repository: its canonical RepoID, so every spelling of one repository shares one per-repository quota.
func StopChildren ¶ added in v0.19.0
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 them to be reaped, then sends SIGKILL to those groups. It returns the number of groups it signaled.
func TryAdmitMaintenance ¶
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.
Types ¶
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 ¶
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 ¶
Acquire takes a slot for key, waiting at most the pool's wait (ErrBusy) or until ctx ends (its error).
func (*Slots) TryAcquire ¶
TryAcquire takes a slot for key if one is free right now.