ad771a6 test(capture): enforce allocation and frame validation guards · nefercap

M AGENTS.md +1 -1


@@ -3,7 +3,7 @@
3	3		- Local-only repository: do not create remotes, publish branches, or access GitHub without explicit permission.
4	4		- Use Go 1.27; normal builds and tests use CGO_ENABLED=0. Enable CGO only for race tests.
5	5		- Follow lightweight hexagonal architecture: cmd/nefercap and internal/app wire internal/core, internal/ports, and internal/adapters. Core imports only stdlib and ports; ports contain no framework types.
6		-	- Use NeferGUI v0.10 for graphical interfaces and zerowrap with a component field for logging. Reuse NeferWL dependency versions where applicable; do not copy unrelated compositor dependencies.
	6	+	- Use NeferGUI v0.1.0 for graphical interfaces and zerowrap with a component field for logging. Reuse NeferWL dependency versions where applicable; do not copy unrelated compositor dependencies.
7	7		- Work in .worktrees/ branches, not directly on main. Merge locally only after checks and review pass.
8	8		- Sign every commit and tag; commit format: type(scope): description.
9	9		- Minimize footprint. Bound buffers, queues and subprocess lifetimes. Reuse frame storage; test and benchmark steady-state allocations. Do not claim zero allocations without measurements.


@@ -3,7 +3,7 @@
3		- Local-only repository: do not create remotes, publish branches, or access GitHub without explicit permission.	3		- Local-only repository: do not create remotes, publish branches, or access GitHub without explicit permission.
4		- Use Go 1.27; normal builds and tests use CGO_ENABLED=0. Enable CGO only for race tests.	4		- Use Go 1.27; normal builds and tests use CGO_ENABLED=0. Enable CGO only for race tests.
5		- Follow lightweight hexagonal architecture: cmd/nefercap and internal/app wire internal/core, internal/ports, and internal/adapters. Core imports only stdlib and ports; ports contain no framework types.	5		- Follow lightweight hexagonal architecture: cmd/nefercap and internal/app wire internal/core, internal/ports, and internal/adapters. Core imports only stdlib and ports; ports contain no framework types.
6	-	- Use NeferGUI v0.10 for graphical interfaces and zerowrap with a component field for logging. Reuse NeferWL dependency versions where applicable; do not copy unrelated compositor dependencies.	6	+	- Use NeferGUI v0.1.0 for graphical interfaces and zerowrap with a component field for logging. Reuse NeferWL dependency versions where applicable; do not copy unrelated compositor dependencies.
7		- Work in .worktrees/ branches, not directly on main. Merge locally only after checks and review pass.	7		- Work in .worktrees/ branches, not directly on main. Merge locally only after checks and review pass.
8		- Sign every commit and tag; commit format: type(scope): description.	8		- Sign every commit and tag; commit format: type(scope): description.
9		- Minimize footprint. Bound buffers, queues and subprocess lifetimes. Reuse frame storage; test and benchmark steady-state allocations. Do not claim zero allocations without measurements.	9		- Minimize footprint. Bound buffers, queues and subprocess lifetimes. Reuse frame storage; test and benchmark steady-state allocations. Do not claim zero allocations without measurements.

M Makefile +19 -17

@@ -1,4 +1,4 @@
1		-	.PHONY: bin build test vet race mocks mocks-check fakes-check arch perf-check check
	1	+	.PHONY: bin build test vet race mod-check mocks mocks-check fakes-check arch perf-check check
2	2
3	3		GOBIN_DIR := $(or $(shell go env GOBIN),$(firstword $(subst :, ,$(shell go env GOPATH)))/bin)
4	4		MOCKERY ?= $(GOBIN_DIR)/mockery

@@ -16,6 +16,9 @@ vet:
16	16		race:
17	17		# cgo is enabled only for the race test binary.
18	18		CGO_ENABLED=1 go test -race ./...
	19	+	# go.mod and go.sum must be tidy (prints the diff and fails otherwise).
	20	+	mod-check:
	21	+	go mod tidy -diff
19	22
20	23		# Regenerate from scratch so mocks of removed interfaces disappear too.
21	24		mocks:

@@ -24,16 +27,9 @@ mocks:
24	27		find internal -name '*_mock_test.go' -delete
25	28		$(MOCKERY)
26	29
27		-	# Checksum of all generated mocks (paths and contents); empty set is valid.
28		-	MOCKSUM = { find internal -type f $ -path 'internal/mocks/' -o -name '_mock_test.go' $ \| LC_ALL=C sort \| xargs -r sha256sum; } \| sha256sum
29	30		MOCKS := internal/mocks ':(glob)internal/*/_mock_test.go'
30		-	# Regenerate and compare checksums (independent of committed state), then also
31		-	# require the mocks to be tracked and clean.
32		-	mocks-check:
33		-	@before=$$($(MOCKSUM)); \
34		-	$(MAKE) --no-print-directory mocks \|\| exit $$?; \
35		-	after=$$($(MOCKSUM)); \
36		-	[ "$$before" = "$$after" ] \|\| { echo 'generated mocks were stale: review and commit the regenerated files' >&2; exit 1; }
	31	+	# Regenerate, then require the mocks to be tracked and unchanged.
	32	+	mocks-check: mocks
37	33		git diff --exit-code -- $(MOCKS)
38	34		@test -z "$$(git ls-files --others --exclude-standard -- $(MOCKS))" \|\| { echo 'untracked generated mocks: commit them' >&2; exit 1; }
39	35

@@ -46,12 +42,18 @@ fakes-check:
46	42		[ $$rc -eq 1 ] \|\| { [ $$rc -eq 0 ] && echo 'handwritten test double: add an interface and a Mockery entry (see AGENTS.md)' >&2; exit 1; }
47	43		arch:
48	44		$(HEXCHECK) -hexcheck.config .hexcheck.yaml -hexcheck.root . ./...
49		-	# Steady-state allocation guards. Extend PERF_TESTS (regexp, exact names) and
50		-	# PERF_PKGS as encoder/wayland tests appear. The preflight fails if no listed
51		-	# test matches, so the guard cannot pass vacuously.
52		-	PERF_TESTS := ^TestFrameAllocations$$
	45	+	# Steady-state allocation guards. PERF_TESTS lists exact test names and PERF_PKGS
	46	+	# the packages holding them; extend both as encoder/wayland tests appear. Every
	47	+	# named test must exist, so the guard cannot pass vacuously.
	48	+	PERF_TESTS := TestFrameAllocations
53	49		PERF_PKGS := ./internal/ports
	50	+	perf_empty :=
	51	+	perf_space := $(perf_empty) $(perf_empty)
	52	+	PERF_RE := ^($(subst $(perf_space),\|,$(strip $(PERF_TESTS))))$$
54	53		perf-check:
55		-	@CGO_ENABLED=0 go test -list '$(PERF_TESTS)' $(PERF_PKGS) \| grep -Eq '$(PERF_TESTS)' \|\| { echo 'perf-check: no test matches $(PERF_TESTS) in $(PERF_PKGS)' >&2; exit 1; }
56		-	CGO_ENABLED=0 go test $(PERF_PKGS) -run '$(PERF_TESTS)' -count=1
57		-	check: vet test arch fakes-check perf-check
	54	+	@out=$$(CGO_ENABLED=0 go test -list '$(PERF_RE)' $(PERF_PKGS)) \|\| { echo "$$out" >&2; exit 1; }; \
	55	+	for t in $(PERF_TESTS); do \
	56	+	printf '%s\n' "$$out" \| grep -qx "$$t" \|\| { echo "perf-check: test $$t not found in $(PERF_PKGS)" >&2; exit 1; }; \
	57	+	done
	58	+	CGO_ENABLED=0 go test $(PERF_PKGS) -run '$(PERF_RE)' -count=1
	59	+	check: mod-check vet test arch fakes-check perf-check

-.PHONY: bin build test vet race mocks mocks-check fakes-check arch perf-check check
+.PHONY: bin build test vet race mod-check mocks mocks-check fakes-check arch perf-check check
 GOBIN_DIR := $(or $(shell go env GOBIN),$(firstword $(subst :, ,$(shell go env GOPATH)))/bin)
 MOCKERY ?= $(GOBIN_DIR)/mockery
 race:
 	# cgo is enabled only for the race test binary.
 	CGO_ENABLED=1 go test -race ./...
+# go.mod and go.sum must be tidy (prints the diff and fails otherwise).
+mod-check:
+	go mod tidy -diff
 # Regenerate from scratch so mocks of removed interfaces disappear too.
 mocks:
 	find internal -name '*_mock_test.go' -delete
 	$(MOCKERY)
-# Checksum of all generated mocks (paths and contents); empty set is valid.
-MOCKSUM = { find internal -type f \( -path 'internal/mocks/*' -o -name '*_mock_test.go' \) | LC_ALL=C sort | xargs -r sha256sum; } | sha256sum
 MOCKS := internal/mocks ':(glob)internal/**/*_mock_test.go'
-# Regenerate and compare checksums (independent of committed state), then also
+# Regenerate, then require the mocks to be tracked and unchanged.
-# require the mocks to be tracked and clean.
+mocks-check: mocks
-mocks-check:
-	@before=$$($(MOCKSUM)); \
-	$(MAKE) --no-print-directory mocks || exit $$?; \
-	after=$$($(MOCKSUM)); \
-	[ "$$before" = "$$after" ] || { echo 'generated mocks were stale: review and commit the regenerated files' >&2; exit 1; }
 	git diff --exit-code -- $(MOCKS)
 	@test -z "$$(git ls-files --others --exclude-standard -- $(MOCKS))" || { echo 'untracked generated mocks: commit them' >&2; exit 1; }
 	[ $$rc -eq 1 ] || { [ $$rc -eq 0 ] && echo 'handwritten test double: add an interface and a Mockery entry (see AGENTS.md)' >&2; exit 1; }
 arch:
 	$(HEXCHECK) -hexcheck.config .hexcheck.yaml -hexcheck.root . ./...
-# Steady-state allocation guards. Extend PERF_TESTS (regexp, exact names) and
+# Steady-state allocation guards. PERF_TESTS lists exact test names and PERF_PKGS
-# PERF_PKGS as encoder/wayland tests appear. The preflight fails if no listed
+# the packages holding them; extend both as encoder/wayland tests appear. Every
-# test matches, so the guard cannot pass vacuously.
+# named test must exist, so the guard cannot pass vacuously.
-PERF_TESTS := ^TestFrameAllocations$$
+PERF_TESTS := TestFrameAllocations
 PERF_PKGS := ./internal/ports
+perf_empty :=
+perf_space := $(perf_empty) $(perf_empty)
+PERF_RE := ^($(subst $(perf_space),|,$(strip $(PERF_TESTS))))$$
 perf-check:
-	@CGO_ENABLED=0 go test -list '$(PERF_TESTS)' $(PERF_PKGS) | grep -Eq '$(PERF_TESTS)' || { echo 'perf-check: no test matches $(PERF_TESTS) in $(PERF_PKGS)' >&2; exit 1; }
+	@out=$$(CGO_ENABLED=0 go test -list '$(PERF_RE)' $(PERF_PKGS)) || { echo "$$out" >&2; exit 1; }; \
-	CGO_ENABLED=0 go test $(PERF_PKGS) -run '$(PERF_TESTS)' -count=1
+	for t in $(PERF_TESTS); do \
-check: vet test arch fakes-check perf-check
+		printf '%s\n' "$$out" | grep -qx "$$t" || { echo "perf-check: test $$t not found in $(PERF_PKGS)" >&2; exit 1; }; \
+	done
+	CGO_ENABLED=0 go test $(PERF_PKGS) -run '$(PERF_RE)' -count=1
+check: mod-check vet test arch fakes-check perf-check

M internal/ports/capture.go +1 -0


@@ -62,6 +62,7 @@ type VideoSettings struct {
62	62		}
63	63
64	64		// VideoWriter has one owner. Start fixes input geometry and reserves a new path.
	65	+	// Start does not encode its frame; pass the first frame explicitly to Write.
65	66		// Write consumes borrowed pixels before returning; it must not queue frames.
66	67		// Close drains and finalizes the encoder with a bounded shutdown deadline.
67	68		// Abort interrupts pending writes and is safe concurrently with Write.


@@ -62,6 +62,7 @@ type VideoSettings struct {
62	}	62		}
63		63
64	// VideoWriter has one owner. Start fixes input geometry and reserves a new path.	64		// VideoWriter has one owner. Start fixes input geometry and reserves a new path.
		65	+	// Start does not encode its frame; pass the first frame explicitly to Write.
65	// Write consumes borrowed pixels before returning; it must not queue frames.	66		// Write consumes borrowed pixels before returning; it must not queue frames.
66	// Close drains and finalizes the encoder with a bounded shutdown deadline.	67		// Close drains and finalizes the encoder with a bounded shutdown deadline.
67	// Abort interrupts pending writes and is safe concurrently with Write.	68		// Abort interrupts pending writes and is safe concurrently with Write.

M internal/ports/errors.go +6 -2

@@ -1,6 +1,9 @@
1	1		package ports
2	2
3		-	import "errors"
	3	+	import (
	4	+	"errors"
	5	+	"io/fs"
	6	+	)
4	7
5	8		var (
6	9		ErrClosed = errors.New("capture resource is closed")

@@ -8,5 +11,6 @@ var (
8	11		ErrUnsupportedFormat = errors.New("unsupported capture pixel format")
9	12		ErrInvalidRegion = errors.New("invalid output-local capture region")
10	13		ErrOutputNotFound = errors.New("capture output not found")
11		-	ErrPathExists = errors.New("capture path already exists")
	14	+	// ErrPathExists is the standard filesystem conflict sentinel.
	15	+	ErrPathExists = fs.ErrExist
12	16		)

 package ports
-import "errors"
+import (
+	"errors"
+	"io/fs"
+)
 var (
 	ErrClosed            = errors.New("capture resource is closed")
 	ErrUnsupportedFormat = errors.New("unsupported capture pixel format")
 	ErrInvalidRegion     = errors.New("invalid output-local capture region")
 	ErrOutputNotFound    = errors.New("capture output not found")
-	ErrPathExists        = errors.New("capture path already exists")
+	// ErrPathExists is the standard filesystem conflict sentinel.
+	ErrPathExists = fs.ErrExist
 )

M internal/ports/frame_test.go +25 -12

@@ -1,6 +1,8 @@
1	1		package ports
2	2
3	3		import (
	4	+	"errors"
	5	+	"strings"
4	6		"testing"
5	7		)
6	8

@@ -10,24 +12,35 @@ func TestFrameValidation(t *testing.T) {
10	12		t.Fatal(err)
11	13		}
12	14		cases := []struct {
13		-	name string
14		-	change func(*Frame)
	15	+	name string
	16	+	frame Frame
	17	+	wantMessage string
	18	+	wantIs error
15	19		}{
16		-	{"zero width", func(f *Frame) { f.Width = 0 }},
17		-	{"negative height", func(f *Frame) { f.Height = -1 }},
18		-	{"oversized width", func(f *Frame) { f.Width = MaxDimension + 1 }},
19		-	{"short stride", func(f *Frame) { f.Stride = 7 }},
20		-	{"oversized storage", func(f *Frame) { f.Stride = MaxFrameBytes }},
21		-	{"unsupported format", func(f *Frame) { f.Format = 42 }},
22		-	{"short storage", func(f *Frame) { f.Pixels = f.Pixels[:23] }},
	20	+	{"zero width", Frame{Width: 0, Height: 1, Stride: 4, Pixels: make([]byte, 4)}, "invalid frame dimensions", nil},
	21	+	{"negative height", Frame{Width: 1, Height: -1, Stride: 4, Pixels: make([]byte, 4)}, "invalid frame dimensions", nil},
	22	+	{"oversized width", Frame{Width: MaxDimension + 1, Height: 1, Stride: (MaxDimension + 1) * 4, Pixels: make([]byte, (MaxDimension+1)*4)}, "invalid frame dimensions", nil},
	23	+	{"oversized height", Frame{Width: 1, Height: MaxDimension + 1, Stride: 4, Pixels: make([]byte, (MaxDimension+1)*4)}, "invalid frame dimensions", nil},
	24	+	{"short aligned stride", Frame{Width: 2, Height: 1, Stride: 4, Pixels: make([]byte, 4)}, "invalid frame stride", nil},
	25	+	{"unaligned stride", Frame{Width: 1, Height: 1, Stride: 6, Pixels: make([]byte, 6)}, "invalid frame stride", nil},
	26	+	// The error family proves storage bounds run before the short-slice check.
	27	+	{"excessive stride", Frame{Width: 1, Height: 2, Stride: MaxFrameBytes/2 + 4}, "invalid frame stride", nil},
	28	+	{"overflow stride", Frame{Width: 1, Height: 2, Stride: int(^uint(0)>>1) &^ 3}, "invalid frame stride", nil},
	29	+	{"unsupported format", Frame{Width: 1, Height: 1, Stride: 4, Pixels: make([]byte, 4), Format: 42}, "", ErrUnsupportedFormat},
	30	+	{"short storage", Frame{Width: 2, Height: 2, Stride: 12, Pixels: make([]byte, 23)}, "short frame storage", nil},
23	31		}
24	32		for _, tc := range cases {
25	33		t.Run(tc.name, func(t *testing.T) {
26		-	f := valid
27		-	tc.change(&f)
28		-	if f.Validate() == nil {
	34	+	err := tc.frame.Validate()
	35	+	if err == nil {
29	36		t.Fatal("accepted invalid frame")
30	37		}
	38	+	if tc.wantIs != nil && !errors.Is(err, tc.wantIs) {
	39	+	t.Fatalf("got %v, want %v", err, tc.wantIs)
	40	+	}
	41	+	if tc.wantMessage != "" && !strings.Contains(err.Error(), tc.wantMessage) {
	42	+	t.Fatalf("got %v, want %s", err, tc.wantMessage)
	43	+	}
31	44		})
32	45		}
33	46		}

 package ports
 import (
+	"errors"
+	"strings"
 	"testing"
 )
 		t.Fatal(err)
 	}
 	cases := []struct {
-		name   string
+		name        string
-		change func(*Frame)
+		frame       Frame
+		wantMessage string
+		wantIs      error
 	}{
-		{"zero width", func(f *Frame) { f.Width = 0 }},
+		{"zero width", Frame{Width: 0, Height: 1, Stride: 4, Pixels: make([]byte, 4)}, "invalid frame dimensions", nil},
-		{"negative height", func(f *Frame) { f.Height = -1 }},
+		{"negative height", Frame{Width: 1, Height: -1, Stride: 4, Pixels: make([]byte, 4)}, "invalid frame dimensions", nil},
-		{"oversized width", func(f *Frame) { f.Width = MaxDimension + 1 }},
+		{"oversized width", Frame{Width: MaxDimension + 1, Height: 1, Stride: (MaxDimension + 1) * 4, Pixels: make([]byte, (MaxDimension+1)*4)}, "invalid frame dimensions", nil},
-		{"short stride", func(f *Frame) { f.Stride = 7 }},
+		{"oversized height", Frame{Width: 1, Height: MaxDimension + 1, Stride: 4, Pixels: make([]byte, (MaxDimension+1)*4)}, "invalid frame dimensions", nil},
-		{"oversized storage", func(f *Frame) { f.Stride = MaxFrameBytes }},
+		{"short aligned stride", Frame{Width: 2, Height: 1, Stride: 4, Pixels: make([]byte, 4)}, "invalid frame stride", nil},
-		{"unsupported format", func(f *Frame) { f.Format = 42 }},
+		{"unaligned stride", Frame{Width: 1, Height: 1, Stride: 6, Pixels: make([]byte, 6)}, "invalid frame stride", nil},
-		{"short storage", func(f *Frame) { f.Pixels = f.Pixels[:23] }},
+		// The error family proves storage bounds run before the short-slice check.
+		{"excessive stride", Frame{Width: 1, Height: 2, Stride: MaxFrameBytes/2 + 4}, "invalid frame stride", nil},
+		{"overflow stride", Frame{Width: 1, Height: 2, Stride: int(^uint(0)>>1) &^ 3}, "invalid frame stride", nil},
+		{"unsupported format", Frame{Width: 1, Height: 1, Stride: 4, Pixels: make([]byte, 4), Format: 42}, "", ErrUnsupportedFormat},
+		{"short storage", Frame{Width: 2, Height: 2, Stride: 12, Pixels: make([]byte, 23)}, "short frame storage", nil},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
-			f := valid
+			err := tc.frame.Validate()
-			tc.change(&f)
+			if err == nil {
-			if f.Validate() == nil {
 				t.Fatal("accepted invalid frame")
 			}
+			if tc.wantIs != nil && !errors.Is(err, tc.wantIs) {
+				t.Fatalf("got %v, want %v", err, tc.wantIs)
+			}
+			if tc.wantMessage != "" && !strings.Contains(err.Error(), tc.wantMessage) {
+				t.Fatalf("got %v, want %s", err, tc.wantMessage)
+			}
 		})
 	}
 }