# uber-go/goleak architecture

> Architecture diagram of the GitHub repository uber-go/goleak, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uber-go/goleak
- Repository: https://github.com/uber-go/goleak

## Overview

##### Project type and purpose
- This is a Go library (“goleak”) designed to detect leaked goroutines in Go test suites. It is not a client-server app but a developer tool/library that hooks into `testing` and the Go runtime to capture and analyze active goroutines at test boundaries.

##### File structure
- Top-level files:
- leaks.go / leaks_test.go: core public API (VerifyNone, VerifyTestMain) and high-level leak-detection logic
- options.go / options_test.go: configuration/options parsing and defaults
- utils_test.go / signal_test.go: miscellaneous helpers and behavior tests
- internal/stack:
- scan.go / scan_test.go and stacks.go / stacks_test.go: the stack–capture and parsing engine, which invokes `runtime.Stack`, splits it into per-goroutine traces, and applies filters
- testdata/: example stack traces for unit tests
- CI and quality:
- .github/workflows: CI pipelines
- .golangci.yml: linting rules
- Makefile: build/coverage/test targets

##### README for additional insights
- Public API: `VerifyNone(t *testing.T)` and `VerifyTestMain(m *testing.M)`—these are the primary integration points
- Warning about `t.Parallel()` and best practices for leak testing
- No external services or databases—pure in-process library

a. Main components
1. Public API Layer (leaks.go, options.go)
2. Test Integration Layer (testmain.go)
3. Stack Scanning Engine (internal/stack: scan.go, stacks.go)
4. Configuration/Options Module (options.go)
5. Runtime Interface (Go runtime’s `runtime.Stack`, `testing` package)
b. Relationships & data flow
- A test calls `VerifyNone` or a TestMain calls `VerifyTestMain`
↓
- API Layer collects configuration and defers leak check to the Stack Scanning Engine
↓
- Scanning Engine calls `runtime.Stack` to retrieve raw stack traces
↓
- Stacks module parses the raw data into structured goroutine objects, applies filters (e.g., known runtime goroutines)
↓
- Results are returned to API Layer, which reports test failure if leaks are detected
c. Architectural patterns & principles
- Layered architecture: API → integration → engine → runtime
- Encapsulation: internal/stack is hidden from public API
- Dependency on Go’s testing framework and runtime only—no external dependencies
- Extensibility: options pattern allows users to adjust filtering or ignore lists
d. Key technologies & libraries
- Go runtime: `runtime.Stack`, goroutine internals
- Go testing: `testing.T`, `testing.M`, TestMain
- Go modules: go.mod, go.sum
- CI: GitHub Actions, golangci-lint

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Public API Layer"
        PublicAPI["Public API\nVerifyNone()\nVerifyTestMain()"]:::publicapi
        Options["Configuration/Options Module\noptions.go\noptions_test.go"]:::config
    end

    subgraph "Test Integration Layer"
        Integration["Test Integration\nTestMain Wrapper\ntestmain.go\ntestmain_test.go"]:::integration
    end

    subgraph "Internal Stack Engine"
        Scanner["Stack Scanning Engine\nScanner\nscan.go\nscan_test.go"]:::engine
        Parser["Parser & Filter\nstacks.go\nstacks_test.go"]:::engine
        Doc["Package Documentation\ndoc.go"]:::engine
        TestData["Test Data\ntestdata/"]:::engine
    end

    Runtime["Go Runtime\nruntime.Stack\ntesting.T/M"]:::runtime

    %% Data Flow
    PublicAPI -->|uses configuration| Options
    PublicAPI -->|integrates via| Integration
    Integration -->|calls| Scanner
    Scanner -->|calls| Runtime
    Runtime -->|returns raw traces| Scanner
    Scanner -->|provides raw data| Parser
    Parser -->|returns filtered results| PublicAPI
    TestData -.->|example stacks for tests| Parser
    Doc -.->|documentation| Scanner

    %% Click Events
    click PublicAPI "https://github.com/uber-go/goleak/blob/master/leaks.go"
    click Options "https://github.com/uber-go/goleak/blob/master/options.go"
    click Integration "https://github.com/uber-go/goleak/blob/master/testmain.go"
    click Scanner "https://github.com/uber-go/goleak/blob/master/internal/stack/scan.go"
    click Parser "https://github.com/uber-go/goleak/blob/master/internal/stack/stacks.go"
    click TestData "https://github.com/uber-go/goleak/tree/master/internal/stack/testdata/"
    click Doc "https://github.com/uber-go/goleak/blob/master/internal/stack/doc.go"

    %% Styles
    classDef publicapi fill:#cce5ff,stroke:#2b4f81,color:#000;
    classDef integration fill:#e2f0d9,stroke:#2f7d32,color:#000;
    classDef engine fill:#d9e2f3,stroke:#433a8b,color:#000;
    classDef config fill:#f8d7da,stroke:#c12a2a,color:#000;
    classDef runtime fill:#f0f0f0,stroke:#6c757d,color:#000;
```
