Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .jules/bolt.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,7 @@
## 2026-07-28 - [Validating Context Cancellation for Blocking OS Executions]
**Learning:** Functions that wrap long-running system operations (such as `exec.CommandContext` or `net.DialContext`) generally handle context cancellation automatically, but early aborts for network calls need explicit testing. Merely relying on lower-level Go standard library propagation does not automatically guarantee zero side-effects if the cancellation happens before execution logic completes in consumer boundaries.
**Action:** Always include fine-grained tests that explicitly pass a pre-cancelled context to network discovery and connection routines (e.g. Ping, LookupAddr) to definitively prove zero leakage of OS processes or goroutines on early aborts.

## 2026-11-12 - [Fine-Grained Cancellation Tests for Network I/O]
**Learning:** During highly concurrent operations involving potentially slow operations like `ReverseDNS` and `GetMAC`, basic validation paths aren't enough to prevent leaks. Even when `context` is propagated, it's vital to simulate slow operations intentionally cancelled by `context.CancelFunc` and monitor `runtime.NumGoroutine()` delta across a short sleep, assuring the worker logic successfully and completely unblocks without stalling indefinitely.
**Action:** Always add explicit active cancellation tests simulating blocked tasks (e.g. `TestReverseDNSCancellationActive`) and track before/after `NumGoroutine` counts to guarantee robust clean-up and prevent goroutine leakage on premature aborts.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added
- **Discovery**: Added `TestReverseDNSCancellationActive` and `TestGetMACCancellationActive` to verify zero goroutine/socket leakage during context cancellation.

## [0.7.0] - 2026-07-30

### Added
Expand Down
2 changes: 0 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,6 @@ Shared Go scanning engine for the CatNet ecosystem. Pure Go library — no binar
| `pkg/export` | `ExportJSON`, `ExportCSV` | Export for `[]results.HostResult` with CSV sanitization. | Stable |
| `pkg/exporter` | `ExportJSON`, `ExportCSV`, `ExportXML` | Export for `*results.ScanReport`. | Stable |
| `pkg/coreerr` | `ErrTimeout`, `ErrCancelled`, `ErrInvalidInput` | Typed error taxonomy for `errors.Is`. | Stable |
| `pkg/store` | `ScanStore`, `NewSQLiteStore` | SQLite scan history. | Deprecated — moving to consumers |
| `pkg/diff` | `Compare`, `HostDiff` | Scan comparison. | Deprecated — moving to consumers |

## Quickstart

Expand Down
58 changes: 58 additions & 0 deletions pkg/discovery/net_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ func TestReverseDNSCancellation(t *testing.T) {

res := ReverseDNS(ctx, "8.8.8.8")
if res != "" {
_ = res
t.Errorf("ReverseDNS() with cancelled context should return empty string, got: %q", res)
}
}
Expand All @@ -80,6 +81,7 @@ func TestGetMACCancellation(t *testing.T) {

res := GetMAC(ctx, "127.0.0.1")
if res != "" {
_ = res
t.Errorf("GetMAC() with cancelled context should return empty string, got: %q", res)
}
}
Expand Down Expand Up @@ -126,3 +128,59 @@ func TestPingCancellationActive(t *testing.T) {
t.Errorf("Goroutine leak detected in active Ping cancellation: before=%d, after=%d", before, after)
}
}

func TestReverseDNSCancellationActive(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
before := runtime.NumGoroutine()

go func() {
time.Sleep(5 * time.Millisecond)
cancel()
}()

res := ReverseDNS(ctx, "8.8.8.8")
if res != "" {
_ = res
// Depending on network speed, it might resolve or not before cancellation,
// but we primarily want to ensure no leakage. Let's just log it if it resolved.
// t.Logf("ReverseDNS returned %q before cancellation", res)
}

for i := 0; i < 10; i++ {
if runtime.NumGoroutine() <= before+1 {
return
}
time.Sleep(10 * time.Millisecond)
}
after := runtime.NumGoroutine()
if after > before+1 {
t.Errorf("Goroutine leak detected in active ReverseDNS cancellation: before=%d, after=%d", before, after)
}
}

func TestGetMACCancellationActive(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
before := runtime.NumGoroutine()

go func() {
time.Sleep(5 * time.Millisecond)
cancel()
}()

res := GetMAC(ctx, "192.0.2.1")
if res != "" {
_ = res
// Just in case it returned something fast
}

for i := 0; i < 10; i++ {
if runtime.NumGoroutine() <= before+1 {
return
}
time.Sleep(10 * time.Millisecond)
}
after := runtime.NumGoroutine()
if after > before+1 {
t.Errorf("Goroutine leak detected in active GetMAC cancellation: before=%d, after=%d", before, after)
}
}
Loading