Add a few comments

Author: jedisct1

dnscrypt-proxy/common.go

@@ -144,6 +144,8 @@ func TrimAndStripInlineComments(str string) string {
 	return strings.TrimSpace(str)
 }
 
+// ExtractHostAndPort parses a string containing a host and optional port.
+// If no port is present or cannot be parsed, the defaultPort is returned.
 func ExtractHostAndPort(str string, defaultPort int) (host string, port int) {
 	host, port = str, defaultPort
 	if idx := strings.LastIndex(str, ":"); idx >= 0 && idx < len(str)-1 {
@@ -154,11 +156,14 @@ func ExtractHostAndPort(str string, defaultPort int) (host string, port int) {
 	return
 }
 
+// ReadTextFile reads a file and returns its contents as a string.
+// It automatically removes UTF-8 BOM if present.
 func ReadTextFile(filename string) (string, error) {
 	bin, err := os.ReadFile(filename)
 	if err != nil {
 		return "", err
 	}
+	// Remove UTF-8 BOM if present
 	bin = bytes.TrimPrefix(bin, []byte{0xef, 0xbb, 0xbf})
 	return string(bin), nil
 }

dnscrypt-proxy/dnsutils.go

@@ -37,15 +37,22 @@ func TruncatedResponse(packet []byte) ([]byte, error) {
 }
 
 func RefusedResponseFromMessage(srcMsg *dns.Msg, refusedCode bool, ipv4 net.IP, ipv6 net.IP, ttl uint32) *dns.Msg {
+	// Create an empty response based on the source message
 	dstMsg := EmptyResponseFromMessage(srcMsg)
+
+	// Add Extended DNS Error (EDE) field
 	ede := new(dns.EDNS0_EDE)
 	if edns0 := dstMsg.IsEdns0(); edns0 != nil {
 		edns0.Option = append(edns0.Option, ede)
 	}
 	ede.InfoCode = dns.ExtendedErrorCodeFiltered
+
+	// Either return with refused code or a synthetic response
 	if refusedCode {
+		// Return a simple refused response
 		dstMsg.Rcode = dns.RcodeRefused
 	} else {
+		// Return a synthetic response
 		dstMsg.Rcode = dns.RcodeSuccess
 		questions := srcMsg.Question
 		if len(questions) == 0 {
@@ -54,6 +61,7 @@ func RefusedResponseFromMessage(srcMsg *dns.Msg, refusedCode bool, ipv4 net.IP,
 		question := questions[0]
 		sendHInfoResponse := true
 
+		// For A records, provide synthetic IPv4 if available
 		if ipv4 != nil && question.Qtype == dns.TypeA {
 			rr := new(dns.A)
 			rr.Hdr = dns.RR_Header{Name: question.Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: ttl}
@@ -64,6 +72,7 @@ func RefusedResponseFromMessage(srcMsg *dns.Msg, refusedCode bool, ipv4 net.IP,
 				ede.InfoCode = dns.ExtendedErrorCodeForgedAnswer
 			}
 		} else if ipv6 != nil && question.Qtype == dns.TypeAAAA {
+			// For AAAA records, provide synthetic IPv6 if available
 			rr := new(dns.AAAA)
 			rr.Hdr = dns.RR_Header{Name: question.Name, Rrtype: dns.TypeAAAA, Class: dns.ClassINET, Ttl: ttl}
 			rr.AAAA = ipv6.To16()

dnscrypt-proxy/pattern_matcher.go

@@ -52,40 +52,47 @@ func isGlobCandidate(str string) bool {
 }
 
 func (patternMatcher *PatternMatcher) Add(pattern string, val interface{}, position int) error {
+	// Determine pattern type based on wildcards and special characters
 	leadingStar := strings.HasPrefix(pattern, "*")
 	trailingStar := strings.HasSuffix(pattern, "*")
 	exact := strings.HasPrefix(pattern, "=")
 	patternType := PatternTypeNone
+
+	// Check for glob pattern with wildcard characters
 	if isGlobCandidate(pattern) {
 		patternType = PatternTypePattern
-		_, err := filepath.Match(pattern, "example.com")
+		_, err := filepath.Match(pattern, "example.com") // Validate pattern syntax
 		if len(pattern) < 2 || err != nil {
 			return fmt.Errorf("Syntax error in block rules at pattern %d", position)
 		}
 	} else if leadingStar && trailingStar {
+		// Substring match (*contains*)
 		patternType = PatternTypeSubstring
 		if len(pattern) < 3 {
 			return fmt.Errorf("Syntax error in block rules at pattern %d", position)
 		}
-		pattern = pattern[1 : len(pattern)-1]
+		pattern = pattern[1 : len(pattern)-1] // Remove stars
 	} else if trailingStar {
+		// Prefix match (starts*)
 		patternType = PatternTypePrefix
 		if len(pattern) < 2 {
 			return fmt.Errorf("Syntax error in block rules at pattern %d", position)
 		}
-		pattern = pattern[:len(pattern)-1]
+		pattern = pattern[:len(pattern)-1] // Remove trailing star
 	} else if exact {
+		// Exact match (=example.com)
 		patternType = PatternTypeExact
 		if len(pattern) < 2 {
 			return fmt.Errorf("Syntax error in block rules at pattern %d", position)
 		}
-		pattern = pattern[1:]
+		pattern = pattern[1:] // Remove = prefix
 	} else {
+		// Default: suffix match (*ends or .ends)
 		patternType = PatternTypeSuffix
 		if leadingStar {
-			pattern = pattern[1:]
+			pattern = pattern[1:] // Remove leading star
 		}
-		pattern = strings.TrimPrefix(pattern, ".")
+		pattern = strings.TrimPrefix(pattern, ".") // Remove leading dot if present
 	}
 	if len(pattern) == 0 {
 		dlog.Errorf("Syntax error in block rule at line %d", position)

dnscrypt-proxy/plugin_allow_name.go

@@ -87,11 +87,12 @@ func (plugin *PluginAllowName) Eval(pluginsState *PluginsState, msg *dns.Msg) er
 	if xweeklyRanges != nil {
 		weeklyRanges = xweeklyRanges.(*WeeklyRanges)
 	}
-	if allowList {
-		if weeklyRanges != nil && !weeklyRanges.Match() {
-			allowList = false
-		}
+
+	// If time-based restrictions exist and don't match current time, don't allow
+	if allowList && weeklyRanges != nil && !weeklyRanges.Match() {
+		allowList = false
 	}
+
 	if allowList {
 		pluginsState.sessionData["whitelisted"] = true
 		if plugin.logger != nil {

dnscrypt-proxy/plugin_block_name.go

@@ -100,6 +100,8 @@ func (plugin *PluginBlockName) Init(proxy *Proxy) error {
 		if len(line) == 0 {
 			continue
 		}
+
+		// Handle time-based restrictions with @timerange format
 		parts := strings.Split(line, "@")
 		timeRangeName := ""
 		if len(parts) == 2 {
@@ -109,6 +111,8 @@ func (plugin *PluginBlockName) Init(proxy *Proxy) error {
 			dlog.Errorf("Syntax error in block rules at line %d -- Unexpected @ character", 1+lineNo)
 			continue
 		}
+
+		// Look up the time range if specified
 		var weeklyRanges *WeeklyRanges
 		if len(timeRangeName) > 0 {
 			weeklyRangesX, ok := (*xBlockedNames.allWeeklyRanges)[timeRangeName]