How 0xerr0r/blocky works
1. What this repository is
- Blocky is a Go-based DNS proxy/ad-blocker. Its runtime job is to accept DNS requests, apply policy and enrichment, then forward to upstream resolvers or answer locally.
2. Primary runtime entrypoints
- main.go / main_static.go build the single binary.
- cmd/ contains the CLI surface: serve, query, lists, cache, healthcheck, validate, blocking, version, and root.
- This means the binary can run as a long-lived DNS service or as an admin/inspection tool.
3. Network ingress and service boundary
- server/ is the transport-facing boundary for DNS and HTTP endpoints.
- The repo supports DNS over UDP/TCP plus HTTP-based endpoints such as DoH and a REST API.
- server_config_trigger* suggests configuration changes can cause live reconfiguration/reloads without restarting the process.
4. Core request-processing pipeline
- resolver/ is the heart of the system: it is a chain of resolver components that decorate or replace each other.
- The chain includes blocking, filtering, hosts-file handling, custom DNS overrides, conditional forwarding, FQDN-only behavior, DNS64, DNSSEC validation, ECS handling, metrics, and query logging.
- The resolver layer is where a query is transformed from an incoming DNS request into a final answer or block response.
5. Upstream selection and forwarding
- resolver/upstream_resolver.go, parallel_best_resolver.go, strict_resolver.go, and upstream_tree_resolver.go indicate multiple strategies for choosing upstream DNS servers.
- The upstream side supports classic DNS transports and encrypted transports, including DoT/DoH and QUIC-related client code.
- This separation makes upstream choice configurable per client group or policy rule.
6. Blocking and policy data
- lists/ handles downloading, caching, and parsing block/allow lists.
- lists/parsers/ supports different list formats such as plain line lists and hosts-file style entries.
- trie/ provides fast domain matching structures for policy enforcement, which is central to ad-blocking and allowlisting performance.
7. Caching subsystem
- cache/ abstracts cache behavior, with implementations for Redis-backed caching and in-memory string/grouped caches.
- cache/prefetching/ adds expiration/prefetch behavior for frequently used DNS answers.
- This layer is used to reduce repeated upstream lookups and improve response latency.
8. External state and coordination
- redis/ provides Redis integration and pub/sub/event bridging.
- The presence of cache/redis.go and config/redis.go shows Redis is an optional external dependency, likely for shared cache or distributed coordination.
- The architecture is otherwise intentionally stateless; Redis is the main shared-state boundary when enabled.
9. Configuration model
- config/ defines the YAML-driven configuration schema and validation for blocking, caching, upstreams, DNSSEC, ECS, query logging, custom DNS, hosts file integration, and more.
- config/migration/ suggests backward-compatible config migration between versions.
- Configuration is therefore a first-class input to the runtime pipeline, not just startup metadata.
10. Observability and audit output
- metrics/ exposes Prometheus-style metrics and ties them into the resolver/event flow.
- querylog/ supports multiple output backends: file, database, logger, or disabled.
- log/ provides request-aware logging context, so operational visibility is part of the request path.
11. Management API and generated interfaces
- api/ contains generated server/client/interface code from an OpenAPI definition.
- This API is distinct from DNS traffic: it is the control/management surface used for inspection and administration.
- web/ and docs/api/openapi.yaml support the human-facing and machine-facing documentation for that management layer.
12. Protocol and security helpers
- resolver/dnssec/ implements DNSSEC validation primitives.
- util/ holds shared DNS/HTTP/TLS helpers, EDNS0 handling, ARPA parsing, and build info.
- These are support libraries that keep protocol-specific logic out of the main pipeline.
13. Operational packaging
- The repo is packaged as a containerized Go service: Dockerfile, .devcontainer, and GitHub Actions workflows cover build, release, test, and docs generation.
- The project is designed for deployment as a single binary or container, with dashboards and docs included, but those are auxiliary to the core DNS service.
14. How the main data flow fits together
- Client DNS request enters server/ → passes through a composed resolver chain in resolver/ → policy/list/trie checks and cache lookups happen → upstream selection/forwarding occurs if needed → response is optionally validated, rewritten, logged, and metered → final answer returns to the client.
- Control-plane actions like config changes, API calls, and list refreshes feed into that pipeline through the config/list/cache/event subsystems.
Main entry points: resolver.go Resolver Chain · config.go Config · server.go Server · upstream_resolver.go Upstream
Components 27
Runtime
CLI entrypoints and process startup
- Main · Builds the Blocky executable
main.go - Static Main · Alternate build entrypoint for static packaging
main_static.go - CLI Root · Shared command wiring for subcommands
cmd/root.go - Serve · Starts the long-lived DNS/HTTP service
cmd/serve.go - Admin Cmds · Inspection and maintenance commands such as query, lists, cache, healthcheck, validate, blocking, and version
cmd/query.go
Serving
DNS and HTTP ingress boundaries
- Server · DNS and HTTP listener boundary
server/server.go - HTTP Endpoints · DoH and REST-facing HTTP handling
server/http.go - Reload Trigger · Triggers live reconfiguration on config changes
server/server_config_trigger.go
Resolution
Composed request-processing pipeline
- Resolver Chain · Composed resolver pipeline that transforms each DNS request
resolver/resolver.go - Blocking · Applies allow/block policy before forwarding
resolver/blocking_resolver.go - Filtering · Applies domain and qtype filtering rules
resolver/filtering_resolver.go - Hosts · Answers from hosts-file style overrides
resolver/hosts_file_resolver.go - Upstream · Forwards queries to selected upstream resolvers
resolver/upstream_resolver.go - Selection · Parallel, strict, and tree-based upstream selection strategies
resolver/parallel_best_resolver.go - DNSSEC · Validates DNSSEC chains and responses
resolver/dnssec_resolver.go - ECS · Handles EDNS client subnet behavior
resolver/ecs_resolver.go
Policy & State
Lists, cache, config, and shared state
- Lists · Downloads, caches, and parses block/allow lists
lists/downloader.go - Trie · Fast domain matching structure for policy enforcement
trie/trie.go - Cache · In-memory and Redis-backed DNS cache layer
cache/cache_interface.go - Config · YAML configuration schema, validation, and migration
config/config.go - Redis · Optional Redis integration for cache and event coordination
redis/redis.go
Observability
Logging, metrics, and query audit
- Metrics · Emits request metrics from the resolution path
resolver/metrics_resolver.go - Query Log · Writes per-query audit records
resolver/query_logging_resolver.go - Metrics Export · Prometheus-style metrics exposure
metrics/metrics.go - Query Log Sink · File, database, logger, or disabled query-log writers
querylog/writer.go
Admin/API
Management API and docs
- Management API · Generated API surface for inspection and administration
api/api_server.gen.go - Web UI · Human-facing API documentation and static assets
web/index.go
Connections 32
- Main → CLI Root: boots · Main binary initializes the CLI command tree
- Static Main → CLI Root: boots · Static build uses the same command tree
- CLI Root → Serve: dispatches · Root CLI selects the service command
- CLI Root → Admin Cmds: dispatches · Root CLI selects admin and inspection commands
- Serve → Server: starts · Serve command starts the network boundary
- Server → HTTP Endpoints: exposes · Server binds HTTP-based endpoints such as DoH and API
- Server → Reload Trigger: watches · Server reacts to configuration changes
- Server → Resolver Chain: routes to · Incoming DNS requests enter the resolver pipeline
- Resolver Chain → Blocking: applies · Core pipeline evaluates blocking policy
- Resolver Chain → Filtering: applies · Core pipeline applies request filtering
- Resolver Chain → Hosts: applies · Core pipeline can answer from hosts overrides
- Resolver Chain → DNSSEC: applies · Core pipeline can validate DNSSEC
- Resolver Chain → ECS: applies · Core pipeline can add or honor ECS behavior
- Resolver Chain → Metrics: observes · Core pipeline emits request metrics
- Resolver Chain → Query Log: audits · Core pipeline writes query logs
- Blocking → Lists: uses · Blocking policy is built from configured lists
- Blocking → Trie: matches · Policy checks use domain matching structures
- Filtering → Config: reads · Filtering rules come from configuration
- Hosts → Config: reads · Hosts overrides are configuration-driven
- DNSSEC → Config: reads · DNSSEC validation is enabled and tuned by config
- Upstream → Selection: selects · Forwarding delegates upstream choice to strategies
- Upstream → Cache: consults · Forwarding can reuse cached answers
- Upstream → Redis: optionally uses · Shared cache or coordination can be backed by Redis
- Cache → Redis: backed by · Cache layer can be implemented on Redis
- Config → Lists: configures · Configuration defines list sources and policy behavior
- Config → Cache: configures · Configuration defines cache behavior
- Config → Upstream: configures · Configuration defines upstream selection and forwarding
- Config → Server: configures · Configuration defines serving endpoints and listeners
- Management API → Config: controls · Management API can inspect or change runtime configuration
- Web UI → Management API: documents · Web assets present the management API documentation
- Metrics Export → Metrics: exports · Metrics subsystem exposes resolver-derived telemetry
- Query Log Sink → Query Log: sinks · Query logging resolver writes into configured sinks