all: adding more function/type documentation

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{

config.go

@@ -24,10 +24,17 @@ import (
 	ctrldnet "github.com/Control-D-Inc/ctrld/internal/net"
 )
 
+// IpStackBoth ...
 const (
-	IpStackBoth  = "both"
+	// IpStackBoth indicates that ctrld will use either ipv4 or ipv6 for connecting to upstream,
-	IpStackV4    = "v4"
+	// depending on which stack is available when receiving the DNS query.
-	IpStackV6    = "v6"
+	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
 }

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")

doh.go

@@ -13,10 +13,9 @@ import (
 )
 
 const (
-	DoHMacHeader  = "x-cd-mac"
+	dohMacHeader         = "x-cd-mac"
-	DoHIPHeader   = "x-cd-ip"
+	dohIPHeader          = "x-cd-ip"
-	DoHHostHeader = "x-cd-host"
+	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)
 			}
 		}
 	}

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, "%")

resolver.go

@@ -12,11 +12,17 @@ import (
 )
 
 const (
-	ResolverTypeDOH    = "doh"
+	// ResolverTypeDOH specifies DoH resolver.
-	ResolverTypeDOH3   = "doh3"
+	ResolverTypeDOH = "doh"
-	ResolverTypeDOT    = "dot"
+	// ResolverTypeDOH3 specifies DoH3 resolver.
-	ResolverTypeDOQ    = "doq"
+	ResolverTypeDOH3 = "doh3"
-	ResolverTypeOS     = "os"
+	// ResolverTypeDOT specifies DoT resolver.
+	ResolverTypeDOT = "dot"
+	// ResolverTypeDOQ specifies DoQ resolver.
+	ResolverTypeDOQ = "doq"
+	// ResolverTypeOS specifies OS resolver.
+	ResolverTypeOS = "os"
+	// ResolverTypeLegacy specifies legacy resolver.
 	ResolverTypeLegacy = "legacy"
 )