memusage

type CaptureFailedError struct{ Cause error }

type ComputeFunc func(ctx context.Context, req Request) (*Response, error)

type Computer struct {
	Capturer  HeapDumpCapturer
	Recoverer LabelRecoverer
	Opts      Options
}

type DefaultLabelRecoverer struct{}

type Diagnostics struct {
	GoVersion string
	GOARCH    string

	// UnsupportedRuntime is true when the heap-native label decoder
	// could not locate runtime.g.labels for this dump, e.g. because the
	// Go version/GOARCH is not in the verified layout table.
	UnsupportedRuntime bool

	// StringMissingCount is the number of goroutines whose label decoding
	// failed because the string bytes (key or value) were not preserved
	// in heap dump object contents. Common for literal pprof.Labels.
	StringMissingCount int

	// FailedGoroutines is the number of goroutines whose label decode
	// failed for any reason (excluding StatusDecoded / StatusNoLabels /
	// StatusUnsupportedRuntime).
	FailedGoroutines int

	// StringMissingGIDs and FailedGIDs identify which goroutines failed
	// label decoding (FailedGIDs is a superset that includes the
	// string-missing goroutines). ComputeFromAnalysis uses them to ignore
	// failures on goroutines that are excluded from matching anyway
	// (system/background goroutines under the default options): an
	// excluded goroutine cannot change the match set, so its decode
	// failure must not fail the request. When both GID sets are nil but
	// the counts are non-zero (hand-constructed Diagnostics), every
	// counted failure is conservatively treated as match-eligible.
	StringMissingGIDs map[uint64]struct{}
	FailedGIDs        map[uint64]struct{}

	Warnings []string
}

type ErrorResponse struct {
	Error     string   `json:"error"`
	Code      string   `json:"code"`
	GoVersion string   `json:"go_version,omitempty"`
	GOARCH    string   `json:"goarch,omitempty"`
	Warnings  []string `json:"warnings"`
}

type HandlerOptions struct {
	Opts                Options
	MaxRequestBodyBytes int64

	// Semaphore is the single-flight gate (capacity-1 channel). When nil
	// the handler creates a private one. Supplying a shared channel lets
	// multiple heap-dumping endpoints (e.g. /debug/memusage and
	// /debug/memusage/bundle) serialize against each other, since each
	// triggers a stop-the-world WriteHeapDump.
	Semaphore chan struct{}
}

type HeapDumpCapturer interface {
	CaptureHeapDump(ctx context.Context, gcBefore bool) (path string, cleanup func(), err error)
}

type LabelRecoverer interface {
	Recover(snap *heapsnapshot.HeapSnapshot, mem *heaplabels.Memory, extra addrspace.Reader) (heaplabels.Result, error)
}

type LabelRecoveryFailedError struct {
	GoVersion        string
	GOARCH           string
	FailedGoroutines int
	Warnings         []string
}

type Options struct {
	// GCBeforeHeapDump triggers runtime.GC() immediately before
	// debug.WriteHeapDump in the production capture path. The pure
	// compute path ignores it.
	GCBeforeHeapDump bool

	// IncludeSystemGoroutines lets system/background goroutines (g0, GC
	// workers, finalizer goroutine, etc.) participate in label matching
	// like ordinary user goroutines. Default false.
	IncludeSystemGoroutines bool

	// DisableProcessMemoryReader turns off the in-process address-space
	// reader the handler opens on Linux, macOS, FreeBSD, and Windows so
	// the heap-label decoder can recover ordinary runtime/pprof string
	// literals that live outside heap object contents. When true, label
	// decoding sees heap object contents only, which makes literal-allocated
	// labels fail with string_missing. Useful in tests and in environments
	// where process memory access is undesirable.
	DisableProcessMemoryReader bool

	// Resource limits. Zero values fall back to the Default* constants.
	MaxLabels          int
	MaxLabelKeyBytes   int
	MaxLabelValueBytes int
}

type ParseFailedError struct{ Cause error }

type Request struct {
	Labels map[string]string `json:"labels"`
}

type Response struct {
	Labels map[string]string `json:"labels"`

	MatchedGoroutines int `json:"matched_goroutines"`

	ReachableObjects int    `json:"reachable_objects"`
	ReachableBytes   uint64 `json:"reachable_bytes"`

	GlobalOverlapObjects int    `json:"global_overlap_objects"`
	GlobalOverlapBytes   uint64 `json:"global_overlap_bytes"`

	SystemOverlapObjects int    `json:"system_overlap_objects"`
	SystemOverlapBytes   uint64 `json:"system_overlap_bytes"`
}

type RuntimeHeapDumpCapturer struct{}

type StringMissingError struct {
	GoVersion string
	GOARCH    string
	Warnings  []string
}

type UnsupportedRuntimeError struct {
	GoVersion string
	GOARCH    string
}

type ValidationError struct {
	Code string
	Msg  string
}