github.com/phuslu/fastdns@v0.8.3-0.20240310041952-69506fc67dd1/README.md (about)

     1  # Fast DNS implementation for Go
     2  
     3  [![godoc][godoc-img]][godoc]
     4  [![release][release-img]][release]
     5  [![goreport][goreport-img]][goreport]
     6  [![coverage][coverage-img]][coverage]
     7  
     8  
     9  ## Features
    10  
    11  * 0 Dependency
    12  * Similar Interface with net/http
    13  * Fast DoH Server Co-create with fasthttp
    14  * Fast DNS Client with rich features
    15  * Compatible metrics with coredns
    16  * High Performance
    17      - 0-allocs dns request parser
    18      - 0-allocs dns records marshaller
    19      - worker pool + message pool
    20      - prefork + reuse_port + set_affinity
    21  
    22  
    23  ## Getting Started
    24  
    25  ### DNS Server
    26  ```go
    27  package main
    28  
    29  import (
    30  	"log"
    31  	"net"
    32  	"net/netip"
    33  	"os"
    34  
    35  	"github.com/phuslu/fastdns"
    36  )
    37  
    38  type DNSHandler struct {
    39  	Debug bool
    40  }
    41  
    42  func (h *DNSHandler) ServeDNS(rw fastdns.ResponseWriter, req *fastdns.Message) {
    43  	if h.Debug {
    44  		log.Printf("%s: CLASS %s TYPE %s\n", req.Domain, req.Question.Class, req.Question.Type)
    45  	}
    46  
    47  	switch req.Question.Type {
    48  	case fastdns.TypeA:
    49  		fastdns.HOST1(rw, req, 60, netip.AddrFrom4([4]byte{8, 8, 8, 8}))
    50  	case fastdns.TypeAAAA:
    51  		fastdns.HOST(rw, req, 60, []netip.Addr{netip.MustParseAddr("2001:4860:4860::8888")})
    52  	case fastdns.TypeCNAME:
    53  		fastdns.CNAME(rw, req, 60, []string{"dns.google"}, []netip.Addr{netip.MustParseAddr("8.8.8.8")})
    54  	case fastdns.TypeSRV:
    55  		fastdns.SRV(rw, req, 60, []net.SRV{{"www.google.com", 443, 1000, 1000}})
    56  	case fastdns.TypeNS:
    57  		fastdns.NS(rw, req, 60, []net.NS{{"ns1.google.com"}, {"ns2.google.com"}})
    58  	case fastdns.TypeMX:
    59  		fastdns.MX(rw, req, 60, []net.MX{{"mail.gmail.com", 10}, {"smtp.gmail.com", 10}})
    60  	case fastdns.TypeSOA:
    61  		fastdns.SOA(rw, req, 60, net.NS{"ns1.google"}, net.NS{"ns2.google"}, 60, 90, 90, 180, 60)
    62  	case fastdns.TypePTR:
    63  		fastdns.PTR(rw, req, 0, "ptr.google.com")
    64  	case fastdns.TypeTXT:
    65  		fastdns.TXT(rw, req, 60, "greetingfromgoogle")
    66  	default:
    67  		fastdns.Error(rw, req, fastdns.RcodeNXDomain)
    68  	}
    69  }
    70  
    71  func main() {
    72  	addr := ":53"
    73  
    74  	server := &fastdns.ForkServer{
    75  		Handler: &DNSHandler{
    76  			Debug: os.Getenv("DEBUG") != "",
    77  		},
    78  		Stats: &fastdns.CoreStats{
    79  			Prefix: "coredns_",
    80  			Family: "1",
    81  			Proto:  "udp",
    82  			Server: "dns://" + addr,
    83  			Zone:   ".",
    84  		},
    85  		ErrorLog: log.Default(),
    86  	}
    87  
    88  	err := server.ListenAndServe(addr)
    89  	if err != nil {
    90  		log.Fatalf("dnsserver error: %+v", err)
    91  	}
    92  }
    93  ```
    94  
    95  ### DNS Client
    96  ```bash
    97  $ go install github.com/phuslu/fastdns/cmd/fastdig@master
    98  $ fastdig ip.phus.lu @8.8.8.8
    99  
   100  ; <<>> DiG 0.0.1-Fastdns <<>> ip.phus.lu
   101  ;; global options: +cmd +noedns
   102  ;; Got answer:
   103  ;; ->>HEADER<<- opcode: Query, status: Success, id: 2775
   104  ;; flags: qr rd ra; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 0
   105  
   106  ;; QUESTION SECTION:
   107  ;ip.phus.lu.            IN      A
   108  
   109  ;; ANSWER SECTION:
   110  ip.phus.lu.     299     IN      CNAME   phus.lu.
   111  phus.lu.        299     IN      A       101.32.116.118
   112  
   113  ;; Query time: 15 msec
   114  ;; SERVER: 8.8.8.8#53(8.8.8.8)
   115  ;; WHEN: Mon Apr 12 22:07:16 +08 2021
   116  ;; MSG SIZE  rcvd: 58
   117  ```
   118  
   119  ### DoH Server
   120  ```bash
   121  $ go install github.com/phuslu/fastdns/cmd/fastdoh@master
   122  $ fastdoh :8080
   123  ```
   124  
   125  ## High Performance
   126  
   127  A Performance result as below, for daily benchmark results see [github actions][benchmark]
   128  ```
   129  # go test -v -cpu=1 -run=none -benchmem -bench=.
   130  goos: linux
   131  goarch: amd64
   132  pkg: github.com/phuslu/fastdns
   133  cpu: AMD EPYC 7763 64-Core Processor
   134  
   135  BenchmarkHOST1-4               	56613120	        21.09 ns/op	       0 B/op	       0 allocs/op
   136  BenchmarkHOST-4                	57722778	        20.82 ns/op	       0 B/op	       0 allocs/op
   137  BenchmarkCNAME-4               	40001464	        30.00 ns/op	       0 B/op	       0 allocs/op
   138  BenchmarkSRV-4                 	26439794	        44.84 ns/op	       0 B/op	       0 allocs/op
   139  BenchmarkNS-4                  	22967035	        52.28 ns/op	       0 B/op	       0 allocs/op
   140  BenchmarkSOA-4                 	19650216	        61.16 ns/op	       0 B/op	       0 allocs/op
   141  BenchmarkPTR-4                 	50205879	        30.12 ns/op	       0 B/op	       0 allocs/op
   142  BenchmarkMX-4                  	39453458	        29.81 ns/op	       0 B/op	       0 allocs/op
   143  BenchmarkTXT-4                 	62278441	        19.15 ns/op	       0 B/op	       0 allocs/op
   144  BenchmarkParseMessage-4        	83152729	        14.84 ns/op	       0 B/op	       0 allocs/op
   145  BenchmarkSetQuestion-4         	37922407	        31.28 ns/op	       0 B/op	       0 allocs/op
   146  BenchmarkSetResponseHeader-4   	336013587	         3.583 ns/op	       0 B/op	       0 allocs/op
   147  BenchmarkDecodeName-4          	52855680	        22.86 ns/op	       0 B/op	       0 allocs/op
   148  BenchmarkAppendHOSTRecord-4    	71025451	        16.81 ns/op	       0 B/op	       0 allocs/op
   149  BenchmarkAppendCNAMERecord-4   	52953403	        23.92 ns/op	       0 B/op	       0 allocs/op
   150  BenchmarkAppendSRVRecord-4     	30775414	        36.37 ns/op	       0 B/op	       0 allocs/op
   151  BenchmarkAppendNSRecord-4      	27102512	        43.92 ns/op	       0 B/op	       0 allocs/op
   152  BenchmarkAppendSOARecord-4     	21295884	        56.13 ns/op	       0 B/op	       0 allocs/op
   153  BenchmarkAppendPTRRecord-4     	62573373	        24.38 ns/op	       0 B/op	       0 allocs/op
   154  BenchmarkAppendMXRecord-4      	43072573	        28.30 ns/op	       0 B/op	       0 allocs/op
   155  BenchmarkAppendTXTRecord-4     	100000000	        11.15 ns/op	       0 B/op	       0 allocs/op
   156  BenchmarkUpdateStats-4         	40084848	        29.85 ns/op	       0 B/op	       0 allocs/op
   157  BenchmarkAppendOpenMetrics-4   	  110046	     10824 ns/op	       0 B/op	       0 allocs/op
   158  BenchmarkEncodeDomain-4        	100000000	        11.54 ns/op	       0 B/op	       0 allocs/op
   159  
   160  PASS
   161  ok  	github.com/phuslu/fastdns	30.430s
   162  ```
   163  
   164  Here is the real-world flamegraph [![flamegraph][flamegraph]][flamegraph] when fastdns reaches **1.4M QPS** on a single machine with Xeon 4216 and Intel X710.
   165  
   166  ## Acknowledgment
   167  This dns server is inspired by [fasthttp][fasthttp], [rawdns][rawdns] and [miekg/dns][miekg/dns].
   168  
   169  [godoc-img]: http://img.shields.io/badge/godoc-reference-blue.svg
   170  [godoc]: https://godoc.org/github.com/phuslu/fastdns
   171  [release-img]: https://img.shields.io/github/v/tag/phuslu/fastdns?label=release
   172  [release]: https://github.com/phuslu/fastdns/releases
   173  [goreport-img]: https://goreportcard.com/badge/github.com/phuslu/fastdns
   174  [goreport]: https://goreportcard.com/report/github.com/phuslu/fastdns
   175  [coverage-img]: http://gocover.io/_badge/github.com/phuslu/fastdns
   176  [coverage]: https://gocover.io/github.com/phuslu/fastdns
   177  [benchmark]: https://github.com/phuslu/fastdns/actions?query=workflow%3Abenchmark
   178  [flamegraph]: https://cdn.jsdelivr.net/gh/phuslu/fastdns/torch.svg
   179  [fasthttp]: https://github.com/valyala/fasthttp
   180  [rawdns]: https://github.com/cirocosta/rawdns
   181  [miekg/dns]: https://github.com/miekg/dns