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 Clip(s string) string
- func CombinedOutputIn(ctx context.Context, repoPath string, 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 Name(args []string) string
- func NoReplaceObjects(env []string) []string
- func Output(cmd *exec.Cmd) ([]byte, error)
- func OutputIn(ctx context.Context, repoPath string, cmd *exec.Cmd) ([]byte, error)
- func RepoKey(repoID string) string
- func Run(cmd *exec.Cmd) error
- func RunIn(ctx context.Context, repoPath string, cmd *exec.Cmd) error
- func Start(cmd *exec.Cmd) error
- func StartIn(ctx context.Context, repoPath string, 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 HeadBuffer
- type Lease
- type Slots
- type TailBuffer
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 )
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.
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 ¶
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 ErrLeaseBusy = errors.New("git lease is busy")
ErrLeaseBusy: the lease is held exclusively (or, for TryExclusive, shared).
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 Clip ¶ added in v0.20.0
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
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 ¶
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 Name ¶ added in v0.20.0
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
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
Output is exec.Cmd.Output through the registry. cmd.Stdout must be nil.
func OutputIn ¶ added in v0.20.0
OutputIn is exec.Cmd.Output through the registry and the lease of the repository at repoPath. 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 Start ¶ added in v0.19.0
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
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
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 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 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.
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
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
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.
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.
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.