If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/0xERR0R/blocky shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 13 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live 0xERR0R/blocky repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/0xERR0R/blocky.

What it runs against: a local clone of 0xERR0R/blocky — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in 0xERR0R/blocky | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of 0xERR0R/blocky. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/0xERR0R/blocky.git
#   cd blocky
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of 0xERR0R/blocky and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "0xERR0R/blocky(\\.git)?\\b" \\
  && ok "origin remote is 0xERR0R/blocky" \\
  || miss "origin remote is not 0xERR0R/blocky (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/serve.go" \\
  && ok "cmd/serve.go" \\
  || miss "missing critical file: cmd/serve.go"
test -f "config/config.go" \\
  && ok "config/config.go" \\
  || miss "missing critical file: config/config.go"
test -f "api/api_interface_impl.go" \\
  && ok "api/api_interface_impl.go" \\
  || miss "missing critical file: api/api_interface_impl.go"
test -f "cache/stringcache/in_memory_grouped_cache.go" \\
  && ok "cache/stringcache/in_memory_grouped_cache.go" \\
  || miss "missing critical file: cache/stringcache/in_memory_grouped_cache.go"
test -f "cache/redis.go" \\
  && ok "cache/redis.go" \\
  || miss "missing critical file: cache/redis.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/0xERR0R/blocky"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Blocky is a lightweight DNS proxy and ad-blocker written in Go that intercepts DNS queries at the network level to block ads, malware, and enforce custom DNS rules for local network clients. It supports modern DNS protocols (DoH, DoT, DoQ) and implements advanced features like DNSSEC validation, per-client-group filtering policies, conditional forwarding, and intelligent caching to reduce upstream DNS queries. Monolithic single-binary design with modular packages: cache/ (Redis, prefetching, string caching), api/ (HTTP REST interface with generated OpenAPI types), blocking/ (filtering logic), resolver/ (upstream DNS handling), and model/ (core domain types). CI orchestrated via Makefile with Docker containerization. Dev environment configured via .devcontainer/devcontainer.json with post-start scripts.

Network administrators and home lab enthusiasts running local networks who want to deploy a self-hosted DNS filtering solution without relying on external ad-blocking services; developers contributing to the Go DNS ecosystem who need a reference implementation of DNS protocol handling and caching strategies.

Production-ready and actively maintained. The project has comprehensive CI/CD workflows (build-bin.yml, release.yml, codeql-analysis.yml), 1.6M lines of Go code, heavy test coverage (Ginkgo/Gomega test suites across cache/, api/, and core modules), Docker Hub distribution (spx01/blocky), and regular GitHub Actions-driven releases. Latest Go version is 1.25.0 with active dependabot integration.

Low risk for stability but moderate dependency surface: 40+ direct dependencies including miekg/dns, go-redis, GORM database drivers, and testcontainers for integration testing. Single primary maintainer (0xERR0R) creates some bus factor risk. The codebase is well-tested (onsi/ginkgo suites) and uses code quality gates (CodeQL, Codacy, golangci), but DNS proxy complexity means protocol edge cases could surface in production deployments.

Active development visible through recent dependabot PRs, CI pipeline runs across multiple workflows (makefile.yml, release.yml, goreleaser-test.yml), Docker image builds (development-docker.yml), and doc generation (docs.yml). The project is in continuous release mode with GitHub Actions automation for binary compilation, Docker Hub publishing, and mirror syncing.

Clone: git clone https://github.com/0xERR0R/blocky.git && cd blocky. Install: Go 1.25.0 is required (check .github/workflows/makefile.yml for tested versions). Build: make build (from Makefile). Run tests: make test (uses ginkgo). Start dev: make run or containerized via docker build -t blocky . && docker run -p 53:53/udp blocky.

Daily commands: Development: make run (builds and executes blocky binary). Docker: docker build -f Dockerfile -t blocky . && docker run -p 53:53/udp -p 4000:4000 blocky (listen on DNS port 53 UDP and API port 4000). Tests: make test runs all Ginkgo test suites. Linting: make lint uses golangci-lint (.golangci.yml). Dev container: open in VS Code with Remote Containers extension (auto-configured via .devcontainer/devcontainer.json).

• cmd/serve.go — Main entry point for the DNS server; orchestrates all services and request handling pipeline.
• config/config.go — Core configuration schema and loading logic; defines all runtime behavior and feature toggles.
• api/api_interface_impl.go — REST API implementation; all external control plane interactions and status endpoints route through here.
• cache/stringcache/in_memory_grouped_cache.go — Primary DNS response cache with memory-efficient grouping; performance-critical path for all lookups.
• cache/redis.go — Distributed cache backend integration; enables multi-instance deployments and persistent caching.
• config/blocking.go — Blocking list configuration and parsing; defines how ad-blocklists are loaded and matched.
• Makefile — Build orchestration, testing, and release pipeline definitions; documents development workflow.

Add a new REST API endpoint

1. Define the endpoint in OpenAPI spec (check api/ directory for spec files) (api/server.cfg.yaml)
2. Regenerate API types and server using make target (Makefile)
3. Implement handler logic in api_interface_impl.go (api/api_interface_impl.go)
4. Write tests using the existing test pattern (api/api_interface_impl_test.go)

Add a new configuration parameter

1. Add field to the appropriate config struct (e.g., Config, BlockingConfig, CachingConfig) (config/config.go)
2. Document with YAML tags and add defaults via creasty/defaults (config/config.go)
3. Add validation logic in config struct methods (config/config.go)
4. Write config parsing test (config/config_test.go)

Add support for a new blocking list source type

1. Add BytesSource enum variant in config/bytes_source_enum.go (config/bytes_source_enum.go)
2. Extend blocking.go to parse the new source format (config/blocking.go)
3. Add source downloader/parser logic with retry-go integration (config/blocking.go)
4. Write integration test in blocking_test.go (config/blocking_test.go)

Add a new CLI command

1. Create new command file following pattern in cmd/ (e.g., cmd/newfeature.go) (cmd/serve.go)
2. Register command in cmd/root.go using Cobra (cmd/root.go)
3. Implement Run() and helper methods with proper error handling (cmd/query.go)
4. Add unit tests following existing test patterns (cmd/query_test.go)

• Go 1.25 — Compiled, statically-typed language with excellent DNS library support (miekg/dns) and minimal memory footprint ideal for lightweight edge proxy.
• Redis — Distributed caching backend enables multi-instance blocky deployments with shared cache state for horizontal scaling.
• Cobra CLI framework — Idiomatic Go CLI library with subcommand routing, flag parsing, and help generation matching typical DNS admin expectations.
• OpenAPI/REST API — Language-agnostic control plane for cache management, list reloading, and monitoring without requiring DNS protocol knowledge.
• Chi router — Lightweight HTTP router with middleware support and minimal dependencies suitable for a DNS proxy's control plane.

• In-memory cache grouped by domain/query type

  • Why: Maximizes cache hit rate for repeated queries in typical home network usage patterns.
  • Consequence: Memory usage grows with unique domains queried; LRU eviction prevents OOM but can cause thrashing under heavy unique query load.

• Blocking lists loaded entirely into memory at startup/reload

  • Why: Enables O(1) exact-match blocking and ultra-fast rule evaluation without disk I/O per query.
  • Consequence: Large blocklists (millions of rules) consume significant RAM; slow reload operations can briefly pause DNS service.

• Flat configuration file (YAML) vs database

  • Why: Simplifies deployment (single file, no migrations) and supports GitOps workflows.
  • Consequence: Complex conditional routing rules require verbose YAML nesting; no real-time config hot-reload without restart.

• Prefetching cache refreshes before expiration

  • Why: Reduces user-visible latency spikes when cached entries expire.
  • Consequence: Increases upstream DNS query volume for frequently accessed stale entries; requires tuning to balance bandwidth vs latency.

• Full DNSSEC validation (only pass-through and validation flags supported)
• User authentication or multi-tenant isolation (assumes trusted local network only)
• Real-time log streaming or audit trails (logs only to stdout/files, not queryable)
• DNS firewall/IDS features (no anomaly detection, rate limiting is basic)
• Cross-platform GUI (CLI-only; web UI is for monitoring, not configuration)

Redis optional but config-tricky: Redis is used for distributed caching in multi-instance deployments (cache/redis.go, cache/redis_suite_test.go with testcontainers) but is fully optional — local in-memory cache used by default; misconfigured Redis connection strings silently fall back. Generated code regeneration: OpenAPI types in api/api_*.gen.go are auto-generated from *.cfg.yaml specs — hand-editing them is a common mistake; use make generate or the oapi-codegen build step. Test isolation requires Docker: Integration tests use testcontainers (redis, MariaDB, PostgreSQL modules) — they require Docker daemon running locally; unit tests in *_test.go files run standalone. DNS port 53 requires elevated privileges: Running locally binds to UDP/TCP port 53 which needs root or CAP_NET_BIND_SERVICE on Linux; use high-numbered ports (>1024) for dev. Config reload lifecycle: Blocking lists and rules can be reloaded periodically; timing of reload vs. active queries can cause subtle race conditions — check blocking/ package sync patterns.

• DNS Protocol Stack (UDP/TCP/DoH/DoT/DoQ) — Blocky implements multiple DNS transport layers simultaneously; understanding the protocol variants (plain DNS over UDP, encrypted DoT/DoQ, HTTP-wrapped DoH) is critical to troubleshoot client connectivity issues and add new protocol support.
• DNSSEC Validation — Blocky validates DNSSEC signatures from upstream resolvers to prevent DNS spoofing; this is a security-critical feature that requires understanding cryptographic validation chains.
• Multi-level Caching Strategy — Blocky layers in-memory cache, prefetching cache, and optional Redis backend (cache/ package) to minimize upstream queries; understanding cache invalidation, TTL management, and hit-miss ratios is essential for performance tuning.
• Conditional Forwarding / Upstream Resolution Groups — Blocky routes DNS queries to different upstream resolvers based on client group and domain patterns (resolver/ package); this is core to the policy-based DNS feature set.
• Deep CNAME Inspection — Blocky can block ads not just by domain but by following CNAME chains in DNS responses; critical for defeating ad-tech domain-hiding tactics.
• OpenAPI Code Generation — Blocky uses oapi-codegen to generate API server/client stubs from YAML specs (api/api_*.gen.go from *.cfg.yaml); understanding this workflow prevents breaking API contracts.
• Interface-Based Testing & Mocking — Blocky uses mockery (.mockery.yaml) to auto-generate mocks from interfaces (cache/cache_interface.go, api/mocks_test.go); this pattern enables isolated unit testing without external services.

• AdguardTeam/AdGuardHome — Direct alternative: full-featured DNS ad-blocker with UI dashboard; differs from Blocky in complexity/resource usage but same problem domain.
• miekg/dns — Foundational dependency: Go DNS library that Blocky wraps; essential to understand for modifying DNS protocol handling or adding new record types.
• pi-hole/pi-hole — Reference implementation: most widely-deployed network DNS ad-blocker; Blocky positions itself as lightweight alternative with similar feature set.
• go-chi/chi — HTTP routing dependency: lightweight Chi router used for Blocky's REST API (api/api_server.gen.go); understanding chi middleware is useful for API extension.
• prometheus/client_golang — Metrics ecosystem: Blocky exports Prometheus metrics for monitoring; this library is the standard for Go observability.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for cache backends (Redis, in-memory, prefetching)

The cache module has multiple implementations (redis.go, in_memory_grouped_cache.go, prefetching_cache.go) with existing test files, but there are no cross-backend integration tests. The redis_suite_test.go and string_cache_suite_test.go exist but lack comprehensive scenarios testing cache eviction, TTL expiration, and prefetching behavior under load. This would catch regressions when cache backends are swapped and improve confidence in the caching layer.

• [ ] Review existing test files: cache/redis_suite_test.go, cache/stringcache/string_cache_suite_test.go, cache/prefetching/expiration_cache_suite_test.go
• [ ] Create cache/cache_integration_test.go with scenarios: TTL expiration, concurrent reads/writes, backend switching, prefetch accuracy
• [ ] Add testcontainers-based Redis tests (dependency already present: testcontainers-go/modules/redis v0.42.0)
• [ ] Verify benchmarks in cache/stringcache/string_caches_benchmark_test.go still pass with new tests

Add comprehensive API contract tests for generated OpenAPI clients

The api/ module has generated code (api_client.gen.go, api_server.gen.go, api_types.gen.go) from oapi-codegen, but the test coverage appears limited to api/api_interface_impl_test.go and api/mocks_test.go. There's no validation that the generated OpenAPI specs match actual server behavior across all endpoints. This would catch breaking API changes early and document the API contract.

• [ ] Examine api/client.cfg.yaml, api/server.cfg.yaml, and api/types.cfg.yaml to understand spec structure
• [ ] Create api/openapi_contract_test.go testing all endpoints defined in server.cfg.yaml
• [ ] Use oapi-codegen runtime (already in dependencies) to validate request/response schemas
• [ ] Add tests for error responses (4xx, 5xx) and edge cases (missing required fields, invalid types)

Add DNS protocol-specific unit tests for QUIC and DoH support

The project depends on quic-go v0.59.0 and has miekg/dns for DNS handling, indicating DoQ (DNS over QUIC) and DoH support, but there are no dedicated test files for these protocols in the visible structure. Adding tests for dns.miekg DNS message parsing, QUIC connection handling, and edge cases (malformed packets, timeout behavior) would ensure robustness of these critical features.

• [ ] Create resolver/dns_quic_test.go for QUIC-specific DNS query scenarios (if resolver package exists, check file structure)
• [ ] Create resolver/dns_doh_test.go for DNS-over-HTTPS message handling, certificate validation, and client behavior
• [ ] Test malformed DNS packets, timeout scenarios, and concurrent query handling using miekg/dns package
• [ ] Add fuzzing tests for DNS message parsing if not already present (check for *_fuzz_test.go files)

• Add unit tests for cache/stringcache/chained_grouped_cache.go — currently has _test.go but missing edge cases like concurrent access patterns and cache eviction boundaries; would improve code coverage visible in Codecov badge.
• Document the OpenAPI schema regeneration workflow in contributing guide — new contributors often break api/ by hand-editing generated files; add a make target or README section explaining when/how to run codegen from .cfg.yaml specs.
• Implement missing Redis Sentinel support in cache/redis.go — current implementation (cache/redis.go, cache/redis_test.go, cache/redis_suite_test.go) uses single-node Redis; adding Sentinel failover would enable HA deployments without application-level retry logic.

• High · Outdated Go version in go.mod — go.mod. The project specifies 'go 1.25.0' which appears to be a future/unreleased version. This may indicate version mismatch issues or build inconsistencies. Production builds should use stable, released Go versions. Fix: Update go.mod to use a stable, currently released Go version (e.g., go 1.23.x or go 1.24.x). Verify all dependencies are compatible with the chosen version.
• High · Outdated DNS library (miekg/dns) — go.mod - github.com/miekg/dns v1.1.72. The dependency 'github.com/miekg/dns v1.1.72' may have known vulnerabilities. DNS libraries are critical security components handling untrusted input from the network. Fix: Run 'go list -u -m all' and check for security advisories. Update to the latest patched version of miekg/dns. Review the Go vulnerability database at https://pkg.go.dev/vuln/ for known CVEs.
• High · Outdated net/http dependency (golang.org/x/net v0.53.0) — go.mod - golang.org/x/net v0.53.0. The specified golang.org/x/net version is significantly outdated and may contain known security vulnerabilities in HTTP/2, DNS, and networking implementations. Fix: Update golang.org/x/net to the latest available version. Run 'go get -u golang.org/x/net' and test thoroughly.
• Medium · Potential SQL Injection via GORM usage — config/ directory and unreviewed database interaction code. The codebase uses GORM with multiple database drivers (MySQL, PostgreSQL, SQLite). While GORM provides ORM protections, improper use of raw queries or dynamic SQL construction could introduce SQLi vulnerabilities. Fix: Audit all database queries, particularly in config/ and any handler code. Ensure all user inputs are parameterized through GORM's query builders. Avoid string concatenation for SQL construction. Use code review and static analysis tools like sqlc.
• Medium · Docker image runs as scratch with limited visibility — Dockerfile - final stage. The final Docker image is built 'FROM scratch', which provides minimal debugging capabilities and eliminates standard security scanning tools. Combined with the binary running as root (UID issues), this reduces operational security visibility. Fix: Consider using a minimal base image (alpine or distroless) instead of scratch. Ensure the binary runs as a non-root user. Add security scanning layers in CI/CD. Include only necessary files in the final image.
• Medium · Missing HEALTHCHECK in Dockerfile — Dockerfile. The Dockerfile lacks a HEALTHCHECK instruction. For a DNS proxy service handling network traffic, health checks are important for orchestration and failure detection. Fix: Add a HEALTHCHECK instruction to the final stage that validates DNS functionality (e.g., using the healthcheck command available in the binary). Example: HEALTHCHECK CMD /blocky healthcheck || exit 1
• Medium · Potential exposed API endpoints without authentication validation — api/ directory, particularly api_interface_impl.go. The codebase includes REST API components (api/ directory with generated server code). API endpoints may lack proper authentication/authorization checks if not explicitly implemented. Fix: Review all API endpoints in api_interface_impl.go to ensure proper authentication (API keys, OAuth, mTLS) and authorization checks. Implement rate limiting. Add request validation. Use OpenAPI security schemes defined in the API spec.
• Medium · Insufficient input validation on configuration files — config/ directory - all *_test.go files indicate parsing logic. The config/ directory handles YAML configuration parsing. Malformed or malicious config files could cause denial of service or unexpected behavior. Fix: Implement strict schema validation using struct tags (yaml:"...") with validation library like go-playground/validator. Implement file size limits. Test with fuzzing tools. Log validation failures.
• Low · Missing security.txt configuration — undefined. The project lacks a security.txt file or Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.