proxy: imp docs

proxy/cache.go

@@ -187,7 +187,11 @@ func (c *cache) SetWithSubnet(m *dns.Msg, ip net.IP, mask uint8) {
 	c.itemsWithSubnet.Set(key, data)
 }
 
-// isCacheable checks if m is valid to be cached.
+// isCacheable checks if m is valid to be cached.  For negative answers it
+// follows RFC 2308 on how to cache NXDOMAIN and NODATA kinds of responses.
+//
+// See https://datatracker.ietf.org/doc/html/rfc2308#section-2.1,
+// https://datatracker.ietf.org/doc/html/rfc2308#section-2.2.
 func isCacheable(m *dns.Msg) bool {
 	switch {
 	case m == nil:
@@ -237,8 +241,12 @@ func hasIPAns(m *dns.Msg) (ok bool) {
 	return false
 }
 
-// isCacheableNegative returns true if m's header has at least one SOA RR and no
-// NS records so that it can be declared authoritative.
+// isCacheableNegative returns true if m's header has at least a single SOA RR
+// and no NS records so that it can be declared authoritative.
+//
+// See https://datatracker.ietf.org/doc/html/rfc2308#section-5 for the
+// information on the responses from the authoritative server that should be
+// cached by the forwarder.
 func isCacheableNegative(m *dns.Msg) (ok bool) {
 	for _, rr := range m.Ns {
 		switch rr.Header().Rrtype {

proxy/cache_test.go

@@ -697,6 +697,7 @@ func TestCache_IsCacheable_negative(t *testing.T) {
 		xx              = "XX."
 	)
 
+	// See https://datatracker.ietf.org/doc/html/rfc2308.
 	testCases := []struct {
 		req  *dns.Msg
 		want assert.BoolAssertionFunc