From 542c4f7daf48012810faab82889866366a673c51 Mon Sep 17 00:00:00 2001 From: Cuong Manh Le Date: Mon, 5 Jun 2023 18:41:48 +0700 Subject: [PATCH] all: adding more function/type documentation --- cmd/ctrld/dns_proxy.go | 3 +++ config.go | 14 +++++++++++--- config_quic.go | 1 + doh.go | 13 ++++++------- internal/router/client_info.go | 11 +++++++++++ resolver.go | 16 +++++++++++----- 6 files changed, 43 insertions(+), 15 deletions(-) diff --git a/cmd/ctrld/dns_proxy.go b/cmd/ctrld/dns_proxy.go index 3498556..c7cc7a1 100644 --- a/cmd/ctrld/dns_proxy.go +++ b/cmd/ctrld/dns_proxy.go @@ -470,6 +470,9 @@ func runDNSServer(addr, network string, handler dns.Handler) (*dns.Server, <-cha return s, errCh } +// runDNSServerForNTPD starts a DNS server listening on router.ListenAddress(). It must only be called when ctrld +// running on router, before router.PreRun() to serve DNS request for NTP synchronization. The caller must call +// s.Shutdown() explicitly when NTP is synced successfully. func runDNSServerForNTPD() (*dns.Server, <-chan error) { dnsResolver := ctrld.NewBootstrapResolver() s := &dns.Server{ diff --git a/config.go b/config.go index 5f37998..bdd335b 100644 --- a/config.go +++ b/config.go @@ -24,10 +24,17 @@ import ( ctrldnet "github.com/Control-D-Inc/ctrld/internal/net" ) +// IpStackBoth ... const ( - IpStackBoth = "both" - IpStackV4 = "v4" - IpStackV6 = "v6" + // IpStackBoth indicates that ctrld will use either ipv4 or ipv6 for connecting to upstream, + // depending on which stack is available when receiving the DNS query. + IpStackBoth = "both" + // IpStackV4 indicates that ctrld will use only ipv4 for connecting to upstream. + IpStackV4 = "v4" + // IpStackV6 indicates that ctrld will use only ipv6 for connecting to upstream. + IpStackV6 = "v6" + // IpStackSplit indicates that ctrld will use either ipv4 or ipv6 for connecting to upstream, + // depending on the record type of the DNS query. IpStackSplit = "split" controlDComDomain = "controld.com" @@ -251,6 +258,7 @@ func (uc *UpstreamConfig) UpstreamSendClientInfo() bool { return false } +// BootstrapIPs returns the bootstrap IPs list of upstreams. func (uc *UpstreamConfig) BootstrapIPs() []string { return uc.bootstrapIPs } diff --git a/config_quic.go b/config_quic.go index b6861b6..085476e 100644 --- a/config_quic.go +++ b/config_quic.go @@ -109,6 +109,7 @@ type parallelDialerResult struct { type quicParallelDialer struct{} +// Dial performs parallel dialing to the given address list. func (d *quicParallelDialer) Dial(ctx context.Context, domain string, addrs []string, tlsCfg *tls.Config, cfg *quic.Config) (quic.EarlyConnection, error) { if len(addrs) == 0 { return nil, errors.New("empty addresses") diff --git a/doh.go b/doh.go index 155361e..f861f2f 100644 --- a/doh.go +++ b/doh.go @@ -13,10 +13,9 @@ import ( ) const ( - DoHMacHeader = "x-cd-mac" - DoHIPHeader = "x-cd-ip" - DoHHostHeader = "x-cd-host" - + dohMacHeader = "x-cd-mac" + dohIPHeader = "x-cd-ip" + dohHostHeader = "x-cd-host" headerApplicationDNS = "application/dns-message" ) @@ -101,13 +100,13 @@ func addHeader(ctx context.Context, req *http.Request, sendClientInfo bool) { if sendClientInfo { if ci, ok := ctx.Value(ClientInfoCtxKey{}).(*ClientInfo); ok && ci != nil { if ci.Mac != "" { - req.Header.Set(DoHMacHeader, ci.Mac) + req.Header.Set(dohMacHeader, ci.Mac) } if ci.IP != "" { - req.Header.Set(DoHIPHeader, ci.IP) + req.Header.Set(dohIPHeader, ci.IP) } if ci.Hostname != "" { - req.Header.Set(DoHHostHeader, ci.Hostname) + req.Header.Set(dohHostHeader, ci.Hostname) } } } diff --git a/internal/router/client_info.go b/internal/router/client_info.go index 97446c0..8fc5709 100644 --- a/internal/router/client_info.go +++ b/internal/router/client_info.go @@ -16,8 +16,10 @@ import ( "github.com/Control-D-Inc/ctrld" ) +// readClientInfoFunc represents the function for reading client info. type readClientInfoFunc func(name string) error +// clientInfoFiles specifies client info files and how to read them on supported platforms. var clientInfoFiles = map[string]readClientInfoFunc{ "/tmp/dnsmasq.leases": dnsmasqReadClientInfoFile, // ddwrt "/tmp/dhcp.leases": dnsmasqReadClientInfoFile, // openwrt @@ -31,6 +33,8 @@ var clientInfoFiles = map[string]readClientInfoFunc{ "/var/dhcpd/var/db/dhcpd.leases": iscDHCPReadClientInfoFile, // Pfsense } +// watchClientInfoTable watches changes happens in dnsmasq/dhcpd +// lease files, perform updating to mac table if necessary. func (r *router) watchClientInfoTable() { if r.watcher == nil { return @@ -65,6 +69,7 @@ func (r *router) watchClientInfoTable() { } } +// Stop performs tasks need to be done before the router stopped. func Stop() error { if Name() == "" { return nil @@ -78,6 +83,7 @@ func Stop() error { return nil } +// GetClientInfoByMac returns ClientInfo for the client associated with the given mac. func GetClientInfoByMac(mac string) *ctrld.ClientInfo { if mac == "" { return nil @@ -91,6 +97,7 @@ func GetClientInfoByMac(mac string) *ctrld.ClientInfo { return val.(*ctrld.ClientInfo) } +// dnsmasqReadClientInfoFile populates mac table with client info reading from dnsmasq lease file. func dnsmasqReadClientInfoFile(name string) error { f, err := os.Open(name) if err != nil { @@ -101,6 +108,7 @@ func dnsmasqReadClientInfoFile(name string) error { } +// dnsmasqReadClientInfoReader likes dnsmasqReadClientInfoFile, but reading from an io.Reader instead of file. func dnsmasqReadClientInfoReader(reader io.Reader) error { r := routerPlatform.Load() return lineread.Reader(reader, func(line []byte) error { @@ -124,6 +132,7 @@ func dnsmasqReadClientInfoReader(reader io.Reader) error { }) } +// iscDHCPReadClientInfoFile populates mac table with client info reading from isc-dhcpd lease file. func iscDHCPReadClientInfoFile(name string) error { f, err := os.Open(name) if err != nil { @@ -133,6 +142,7 @@ func iscDHCPReadClientInfoFile(name string) error { return iscDHCPReadClientInfoReader(f) } +// iscDHCPReadClientInfoReader likes iscDHCPReadClientInfoFile, but reading from an io.Reader instead of file. func iscDHCPReadClientInfoReader(reader io.Reader) error { r := routerPlatform.Load() s := bufio.NewScanner(reader) @@ -172,6 +182,7 @@ func iscDHCPReadClientInfoReader(reader io.Reader) error { return nil } +// normalizeIP normalizes the ip parsed from dnsmasq/dhcpd lease file. func normalizeIP(in string) string { // dnsmasq may put ip with interface index in lease file, strip it here. ip, _, found := strings.Cut(in, "%") diff --git a/resolver.go b/resolver.go index 0180762..3162d62 100644 --- a/resolver.go +++ b/resolver.go @@ -12,11 +12,17 @@ import ( ) const ( - ResolverTypeDOH = "doh" - ResolverTypeDOH3 = "doh3" - ResolverTypeDOT = "dot" - ResolverTypeDOQ = "doq" - ResolverTypeOS = "os" + // ResolverTypeDOH specifies DoH resolver. + ResolverTypeDOH = "doh" + // ResolverTypeDOH3 specifies DoH3 resolver. + ResolverTypeDOH3 = "doh3" + // ResolverTypeDOT specifies DoT resolver. + ResolverTypeDOT = "dot" + // ResolverTypeDOQ specifies DoQ resolver. + ResolverTypeDOQ = "doq" + // ResolverTypeOS specifies OS resolver. + ResolverTypeOS = "os" + // ResolverTypeLegacy specifies legacy resolver. ResolverTypeLegacy = "legacy" )