ring-detecting-goroutine-leaks

name

ring:detecting-goroutine-leaks

description

Detecting goroutine leaks in Go: greps for goroutine patterns, audits goleak coverage (VerifyTestMain/VerifyNone), runs goleak, and dispatches ring:backend-go to fix leaks and add regression tests. Use after implementation or during review when code spawns goroutines or a leak is suspected. Runs before ring:reviewing-code. Skip for non-Go or code with no goroutines. Skip for panic/silent-death observability (use ring:using-runtime).

Goroutine Leak Testing

When to use

• Code contains goroutine patterns (go func(), go methodCall())
• After implementation or during code review
• Suspected memory leak in production
• Need to verify goroutine-heavy code doesn't leak

Skip when

• Codebase contains no goroutine usage
• Not a Go project
• Task is documentation-only, configuration-only, or non-code
• Changes do not touch any concurrent code paths

Sequence

Runs before: ring:reviewing-code Runs after: ring:implementing-tasks

Related

Complementary: ring:backend-go

Standards: WebFetch https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang/architecture.md → "Goroutine Leak Detection" section.

Step 1: Detect Goroutine Patterns

# Find goroutine patterns (excluding tests, go.mod, go.sum)
grep -rn "go func()\|go [a-zA-Z_][a-zA-Z0-9_]*\.\|go [a-zA-Z_][a-zA-Z0-9_]*(" \
  --include="*.go" \
  {target_path} \
  | grep -v "_test.go" \
  | grep -v "go.mod\|go.sum\|golang.org"

Goroutine patterns:

• go func() — anonymous goroutine
• go methodCall( — direct call
• go obj.Method( — method call
• for ... := range ch — channel consumer

Exclude: go.mod/go.sum, golang.org imports, comments, string literals.

Step 2: Verify goleak Coverage

# Package-level
grep -rn "goleak.VerifyTestMain" --include="*_test.go" {target_path}

# Per-test
grep -rn "goleak.VerifyNone" --include="*_test.go" {target_path}

Requirements:

• Every package with goroutines → goleak.VerifyTestMain(m) in TestMain
• Critical goroutines → defer goleak.VerifyNone(t) per-test

Step 3: Run goleak

go test -v ./... -run TestMain 2>&1 | grep -E "goleak|leak|goroutine|PASS|FAIL"

Leak output looks like:

goleak.go:89: found unexpected goroutines:
    [Goroutine 7 in state chan receive, with myapp/internal/worker.(*Worker).run on top of the stack:]

Step 4: Dispatch Fix (if leaks found)

Task:
  subagent_type: "ring:backend-go"
  description: "Fix goroutine leak in {package_path}"
  prompt: |
    Fix goroutine leak and add goleak regression test.

    Package: {package_path}
    File: {file}:{line}
    Leak output:
    {goleak_output}

    Standards: Load architecture.md via WebFetch → Goroutine Leak Detection section.

    Requirements:
    1. Fix leak — ensure proper shutdown (context cancellation, close channels, cancel goroutines)
    2. Add goleak.VerifyTestMain(m) to TestMain in package
    3. Add specific test proving no leak occurs

    
    
        
       {   {} }
         {
        {
         {
           {
                 
            
              
          }
        }
      }
    }

       
       {
      
    }
    

    
       
      
      

          

Output Format

## Goroutine Detection Summary

| Metric | Value |
|--------|-------|
| Target path | {target_path} |
| Files with goroutines | N |
| Packages analyzed | N |

## goleak Coverage
| Package | Goroutine Files | goleak Present | Status |
|---------|----------------|---------------|--------|

Coverage: X/Y packages (Z%)

## Leak Findings
| Package | File:Line | Pattern | Status |
|---------|-----------|---------|--------|

Leaks detected: N

## Actions
{PASS: goleak present, no leaks}
{or: Dispatched ring:backend-go to fix N leaks}