Enhance Makefile and documentation for validation workflow

- Added new targets in the Makefile for validation, including `run-validation`, `validate-check`, and `validate-kill`, to streamline the testing process with external tools like SteamPrefill.
- Introduced a `setcap` target to manage necessary capabilities for running the server on port 80 without root access.
- Updated README.md to include detailed instructions for validating functionality, including quick start guides and troubleshooting tips.
- Improved .gitignore to exclude validation artifacts and logs, ensuring a cleaner repository.
This commit is contained in:
2026-05-28 04:15:24 -05:00
parent c3464d692e
commit 3fd72705fc
6 changed files with 585 additions and 12 deletions
+81 -11
View File
@@ -33,15 +33,85 @@ bench: deps ## Run all benchmarks (MemoryFS + DiskFS variants, including all evi
@go test -bench=. -benchmem -run=^$ -benchtime=1s ./vfs/disk
@echo "Bench done."
setcap: build ## Explicitly set cap_net_bind_service on the (just-built) binary for port 80 use outside validate targets
@echo "Setting cap_net_bind_service on the binary so it can listen on port 80 as your normal user..."
@sudo setcap 'cap_net_bind_service=+ep' dist/default_linux_amd64_v1/steamcache2
@echo "Done. You should now be able to run 'make run-validation' as your normal user (no root)."
validate run-validation: build ## Start steamcache2 on :80 with small test caches (foreground)
@echo "=== Starting steamcache2 in validation mode ==="
@echo "Port 80 + small memory/disk caches (for exercising disk tier, GC, etc.)"
@echo "Press Ctrl-C to stop the server."
@echo ""
@BINARY=dist/default_linux_amd64_v1/steamcache2; \
if [ "$$(id -u)" -ne 0 ] && ! getcap "$$BINARY" 2>/dev/null | grep -q cap_net_bind_service; then \
echo "Setting cap_net_bind_service on the freshly built binary (sudo may prompt)..."; \
sudo setcap 'cap_net_bind_service=+ep' "$$BINARY" || { \
echo "ERROR: setcap failed (or was cancelled)."; \
echo "You can run 'make setcap' manually, then retry 'make validate'."; \
exit 1; \
}; \
fi; \
if [ "$$(id -u)" -ne 0 ] && ! getcap "$$BINARY" 2>/dev/null | grep -q cap_net_bind_service; then \
echo "ERROR: Port 80 still requires the capability after setcap attempt."; \
echo "Run 'make setcap' and retry."; \
exit 1; \
fi; \
exec "$$BINARY" --config docs/examples/validate-config.yaml --log-level info
validate-check: ## Quick post-benchmark sanity check against a running steamcache2 (default port 80, override with PORT=xxxx)
@echo "=== steamcache2 Full Function Validation Report ==="
@PORT="$${PORT:-80}"; \
echo "Server: http://localhost:$$PORT"; \
curl -s --max-time 5 "http://localhost:$$PORT/metrics" || echo "(could not reach /metrics on port $$PORT - is the server running?)"; \
echo ""; \
echo "Tip: also inspect recent server logs for errors, coalesced hits, and disk activity."
prefill: ## Download latest SteamPrefill into bin/steam-prefill/SteamPrefill (gitignored)
@./scripts/download-prefill.sh
validate-kill: ## Kill leftover steamcache2 processes (safer, checks process name)
@echo "Looking for steamcache2 processes on common validation ports (80 is primary)..."
@for port in 80 8040 8080; do \
pids=""; \
if command -v ss >/dev/null 2>&1; then \
pids=$$(ss -tlnp 2>/dev/null | grep ":$${port} " | sed -n 's/.*pid=\([0-9]*\).*/\1/p' | sort -u); \
fi; \
if [ -z "$$pids" ] && command -v lsof >/dev/null 2>&1; then \
pids=$$(lsof -ti :$${port} 2>/dev/null | sort -u); \
fi; \
for pid in $$pids; do \
proc=$$(ps -p $$pid -o comm= 2>/dev/null || true); \
cmd=$$(ps -p $$pid -o cmd= 2>/dev/null || true); \
if echo "$$proc $$cmd" | grep -qi "steamcache"; then \
echo " Killing steamcache2 (port $$port, PID $$pid, $$proc)"; \
kill -TERM $$pid 2>/dev/null || true; \
sleep 0.2; \
kill -0 $$pid 2>/dev/null && kill -9 $$pid 2>/dev/null || true; \
else \
echo " Skipping PID $$pid on port $$port (not steamcache2: $$proc)"; \
fi; \
done; \
done
@echo "Validation server cleanup complete."
help: ## Show this help message
@echo steamcache2 Makefile
@echo Available targets:
@echo run Run the application (cross-platform via go run)
@echo run-debug Run the application with debug logging (cross-platform)
@echo build Build the application (goreleaser snapshot)
@echo test Run all tests
@echo test-race Run all tests with the race detector
@echo lint Run golangci-lint + review label check
@echo check-review-labels Fail on temporary review labels (P*, T*, I*, R*, etc.)
@echo deps Download dependencies
@echo clean Remove build/test artifacts
@echo "steamcache2 Makefile"
@echo "Available targets:"
@echo " run Run the application (cross-platform via go run)"
@echo " run-debug Run the application with debug logging (cross-platform)"
@echo " build Build the application (goreleaser snapshot)"
@echo " test Run all tests"
@echo " test-race Run all tests with the race detector"
@echo " lint Run golangci-lint + review label check"
@echo " check-review-labels Fail on temporary review labels (P*, T*, I*, R*, etc.)"
@echo " deps Download dependencies"
@echo " clean Remove build/test artifacts"
@echo " bench Run low-level VFS microbenchmarks"
@echo " validate / run-validation Start server on :80 (builds, auto-setcaps fresh binary, then runs as normal user)"
@echo " setcap Explicitly set cap on current build (for port 80 use outside validate)"
@echo " validate-check Quick /metrics report after running a workload"
@echo " validate-kill Kill leftover steamcache2 processes (safer)"
@echo " prefill Download latest SteamPrefill into bin/steam-prefill/ (for use with run-validation)"