{"id":25014195,"url":"https://github.com/sumitbhuia/godns","last_synced_at":"2025-09-04T03:42:07.050Z","repository":{"id":275667659,"uuid":"926122148","full_name":"sumitbhuia/GoDNS","owner":"sumitbhuia","description":"High-Performance, RFC-Compliant Recursive DNS Resolver","archived":false,"fork":false,"pushed_at":"2025-03-10T08:14:36.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-10T09:29:15.944Z","etag":null,"topics":["dns-server","golang","goroutines","low-latency-http","network-programming"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sumitbhuia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-02T15:57:55.000Z","updated_at":"2025-03-10T08:14:40.000Z","dependencies_parsed_at":"2025-03-10T09:25:23.374Z","dependency_job_id":"90af3de1-d4e2-4795-8df9-605a999928f8","html_url":"https://github.com/sumitbhuia/GoDNS","commit_stats":null,"previous_names":["sumitbhuia/godns"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumitbhuia%2FGoDNS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumitbhuia%2FGoDNS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumitbhuia%2FGoDNS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumitbhuia%2FGoDNS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sumitbhuia","download_url":"https://codeload.github.com/sumitbhuia/GoDNS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246277360,"owners_count":20751549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dns-server","golang","goroutines","low-latency-http","network-programming"],"created_at":"2025-02-05T07:18:00.153Z","updated_at":"2025-09-04T03:42:07.037Z","avatar_url":"https://github.com/sumitbhuia.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚡ GoDNS - High-Performance DNS Resolver in Go\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-1.18+-00ADD8?style=for-the-badge\u0026logo=go\" alt=\"Go Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20windows-blue?style=for-the-badge\u0026logo=linux\" alt=\"Platform\"\u003e\n    \n### Primary Protocol Documentation\n- [RFC 1035: DNS Implementation and Specification](https://datatracker.ietf.org/doc/html/rfc1035)\n- [RFC 6891: Extension Mechanisms for DNS (EDNS(0))](https://datatracker.ietf.org/doc/html/rfc6891)\n\nGoDNS is a DNS resolver built from scratch in Go, designed to be RFC 1035 compliant. This project demonstrates core networking concepts by implementing the DNS protocol, featuring a concurrent, non-blocking architecture, and a comprehensive test suite with performance benchmarks.\n\n## ✨ Key Features\n\n* **RFC 1035 Compliant:** Correctly parses and serializes DNS messages, including headers, questions, and resource records.\n* **Concurrent by Design:** Uses goroutines to handle multiple incoming queries simultaneously without blocking, maximizing CPU utilization.\n* **DNS Message Compression:** Implements label compression and decompression with pointer support to reduce message size, a key feature of the DNS protocol.\n* **Built-in Forwarder:** Forwards queries it can't resolve to an upstream resolver (e.g., Google's `8.8.8.8`).\n* **Extensively Tested:** Includes unit, integration, and performance benchmark tests to ensure correctness and efficiency.\n\n---\n\n\n## 🚀 Performance Analysis\n\nThe server was benchmarked to measure its two key performance indicators: **latency** (speed) and **throughput** (capacity).\n\n**Test Conditions:** These tests were conducted in a controlled local environment (on a single machine) to measure the raw processing power of the application's code, isolating it from real-world network delays. This provides a clear baseline of the server's core efficiency.\n\n#### Query Latency: How *Fast* is a Single Request?\n\nThis graph shows the time it takes for a single query to be processed by the server. **Lower numbers are better.** The box plot visualizes the consistency of the server's response time over many runs, with the green line representing the average (median) speed.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"benchmark_latency.png\" alt=\"Benchmark Latency Results\" width=\"600\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003eThis shows that the server consistently responds very quickly, establishing an efficient baseline for a single transaction.\u003c/em\u003e\n\u003c/p\u003e\n\n#### Server Throughput: How *Much* Can It Handle at Once?\n\nThis graph shows how many queries the server can handle per second when processing many requests in parallel. **Higher numbers are better.** This demonstrates the effectiveness of the concurrent architecture using Go's goroutines.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"benchmark_throughput.png\" alt=\"Benchmark Throughput Results\" width=\"600\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003eThe result confirms the server's non-blocking design can effectively scale to handle a high volume of simultaneous queries.\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## 🛠️ Getting Started\n\n### Prerequisites\n\n* Go 1.18 or newer\n\n### 1. Clone the Repository\n\n```sh\ngit clone https://github.com/sumitbhuia/GoDNS.git\ncd GoDNS\n````\n\n### 2\\. Build the Binary\n\n```sh\n# The main package is in the root directory\ngo build -o godns main.go\n```\n\n### 3\\. Run the Server\n\nThe server listens on port 53 by default, which requires root privileges.\n\n```sh\nsudo ./godns\n```\n\nTo run on a non-privileged port (e.g., 5353) for development:\n\n```sh\n./godns -addr=\":5353\"\n```\n\n-----\n\n## ✅ Testing\n\nThe project includes a comprehensive test suite.\n\n### Run All Tests\n\nThis command runs all unit and integration tests.\n\n```sh\ngo test ./...\n```\n\n### Run Benchmarks\n\nThis command will run the performance benchmarks and output the results to your console.\n\n```sh\ngo test -bench=. -benchmem ./...\n```\n\n-----\n\n## How It Works\n\nGoDNS listens for incoming DNS queries over UDP. When a query is received, a new goroutine is spawned to handle it, ensuring the server remains responsive.\n\n1.  **Parsing:** The raw byte query is parsed into a Go struct according to RFC 1035 specifications. This includes decoding the domain name, which may use pointer-based compression.\n2.  **Forwarding:** The query is then packed back into its binary format and forwarded to an upstream DNS resolver (e.g., `8.8.8.8`).\n3.  **Responding:** When the upstream server responds, GoDNS receives the response and relays it back to the original client, completing the cycle.\n\n\u003cdetails\u003e\n      \u003csummary\u003eMore Details - Architecture\u003c/summary\u003e\n    \n## Protocol Architecture\n\n### Core Implementation Components\n- **UDP Transport Layer**: Non-blocking datagram processing with concurrent goroutine dispatch\n- **DNS Protocol Layer**: RFC1035-compliant message encoding/decoding with compression support\n- **Resource Record Handler**: Polymorphic RR type processing with binary-safe implementations\n- **Query Propagation**: Asynchronous upstream resolver integration with timeout semantics\n\n### Protocol Specifications\n```go\ntype DNSHeader struct {\n    ID      uint16 // Transaction identifier\n    Flags   uint16 // Control flags (QR|Opcode|AA|TC|RD|RA|Z|RCODE)\n    QDCount uint16 // Question section cardinality\n    ANCount uint16 // Answer section RR count\n    NSCount uint16 // Authority section RR count\n    ARCount uint16 // Additional section RR count\n}\n\ntype DNSQuestion struct {\n    Name  string  // Domain name sequence\n    Type  uint16  // RR type identifier\n    Class uint16  // Class identifier\n}\n\ntype DNSRecord struct {\n    Name     string  // Domain name sequence\n    Type     uint16  // RR type identifier\n    Class    uint16  // Class identifier\n    TTL      uint32  // Time-to-live\n    RDLength uint16  // RDATA length\n    RData    []byte  // Resource data\n}\n```\n\n## Implementation Architecture\n\n### Protocol Processing Pipeline\n\n#### Message Parser Implementation\n- Binary-safe buffer management for DNS wire format\n- Domain name label compression/decompression with pointer traversal\n- Resource record serialization with length-prefixed encoding\n- Transaction ID correlation for asynchronous responses\n\n#### Network Stack Integration\n- UDP socket multiplexing with Go runtime scheduler\n- Concurrent query handling via goroutine dispatch\n- Configurable upstream resolver interface\n- Structured error propagation and logging\n\n### Binary Wire Format Specification\n\n#### DNS Header Structure (96 bits)\n| Field      | Bit Offset | Length | Semantic Definition |\n|------------|------------|--------|-------------------|\n| ID         | 0          | 16     | Query identifier for transaction correlation |\n| Flags      | 16         | 16     | Protocol control bits |\n| QDCOUNT    | 32         | 16     | Question section cardinality |\n| ANCOUNT    | 48         | 16     | Answer section RR count |\n| NSCOUNT    | 64         | 16     | Authority section RR count |\n| ARCOUNT    | 80         | 16     | Additional section RR count |\n\n#### Message Compression Algorithm\n- Label pointer detection with 2-bit discrimination\n- Offset-based compression with 14-bit pointer space\n- Recursive decompression with cycle detection\n- Length-prefixed label encoding\n\n## Implementation Capabilities\n\n### Protocol Features\n- RFC1035-compliant message processing\n- Concurrent query handling\n- Upstream resolver integration\n- Error propagation and recovery\n- Domain name compression support\n\n### Technical Architecture\n- Non-blocking I/O operations\n- Concurrent goroutine dispatch\n- Binary-safe buffer handling\n- Resource lifecycle management\n\n    \n\u003c/details\u003e\n\n\n# ☎️ Contact\n\n  * **Email:** `sumitbhuia100@gmail.com`\n  * **Twitter:** [@bhuia\\_sumit](https://twitter.com/bhuia_sumit)\n\n---\n   \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumitbhuia%2Fgodns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsumitbhuia%2Fgodns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumitbhuia%2Fgodns/lists"}