How bernoussama/mercury works
Main Components
• DNS Request Handler: Incoming DNS queries are received, likely through the entry point defined in cmd/serve.go.
• DNS Module: The core logic resides in the "dns" package (dns/dns.go and associated utility functions). This module handles query parsing, processing, and forming responses.
• Cache System: The "cache" package (cache/cache.go) is responsible for caching DNS query results, reducing the number of external requests.
• Zones Loader/Processor: The "zones" directory (with zone files like example.com.yml) represents authoritative zones. Mercury checks these configurations to provide authoritative answers.
• Recursive Resolver: A key feature whereby Mercury, if a query isn’t answered locally, will perform a recursive lookup using the Internet’s root servers.
• DNS Sinkhole: Although not a separate package, this capability is integrated into query processing logic to block or filter domains (for ad-blocking).
• Infrastructure & Deployment: Configuration files like Dockerfile, compose.yaml, and dev_compose.yaml indicate that Mercury is containerized and can be deployed using Docker or systemd.
Relationships and Interactions
• Incoming Client Requests: DNS queries arrive via UDP/TCP on configured ports (as defined in the Docker compose service and possibly in the Dockerfile).
• Request Routing: The main entry (main.go, cmd/root.go, and cmd/serve.go) dispatches queries to the dns package.
• Decision Branching: Within the DNS module, a decision is made:
• If the query matches a zone defined in the "zones" folder, handle it as an authoritative lookup.
• If not, pass the request to the recursive resolver to contact external root servers.
• Additionally, check if the requested domain should be sinkholed.
• Cache Usage: Before external resolution, check the cache module to see if the answer is already stored. After processing, update the cache accordingly.
• Concurrency: Parallel handling of queries is integrated into the design so that multiple clients can be serviced concurrently.
Architectural Patterns and Design Principles
• Separation of Concerns: Each main function is clearly subdivided into independent modules (e.g., DNS processing, caching, zone management).
• Modular Design: The clear directory structure (cmd, dns, cache, zones) keeps logic isolated and encourages reusability.
• Containerization: Use of Dockerfiles and Compose files shows the project is designed to be easily deployed in containerized environments.
• Configuration Driven: The external configuration (zone files, Docker compose) allows dynamic modification without changing the core code.
Incorporate Relevant Technologies
• Go as the primary language – noted by the main.go and other .go files.
• Docker: Emphasized by Dockerfile, compose.yaml, and dev_compose.yaml for deployment.
• CI/CD Workflows: GitHub Actions workflows (.github/workflows) indicate automated build and release pipelines, which are essential for continuous integration but typically outside the core system architecture.