add test and docs

Change-Id: Ib2ffbc1d77c82ed3d32c660d53b5cec741936cb2

src/net/dnsclient_unix.go

@@ -318,6 +318,8 @@ func (r *Resolver) tryOneName(ctx context.Context, cfg *dnsConfig, name string,
 
 			if err := checkHeader(&p, h); err != nil {
 				if err == errNoSuchHost {
+					// The name does not exist, so trying
+					// another server won't help.
 					return p, server, newDNSError(errNoSuchHost, name, server)
 				}
 				lastErr = newDNSError(err, name, server)
@@ -326,6 +328,8 @@ func (r *Resolver) tryOneName(ctx context.Context, cfg *dnsConfig, name string,
 
 			if err := skipToAnswer(&p, qtype); err != nil {
 				if err == errNoSuchHost {
+					// The name does not exist, so trying
+					// another server won't help.
 					return p, server, newDNSError(errNoSuchHost, name, server)
 				}
 				lastErr = newDNSError(err, name, server)

src/net/lookup_test.go

@@ -1630,3 +1630,29 @@ func TestLookupNoSuchHost(t *testing.T) {
 		})
 	}
 }
+
+func TestDNSErrorUnwrap(t *testing.T) {
+	rDeadlineExcceeded := &Resolver{PreferGo: true, Dial: func(ctx context.Context, network, address string) (Conn, error) {
+		return nil, context.DeadlineExceeded
+	}}
+	rCancelled := &Resolver{PreferGo: true, Dial: func(ctx context.Context, network, address string) (Conn, error) {
+		return nil, context.Canceled
+	}}
+
+	_, err := rDeadlineExcceeded.LookupHost(context.Background(), "test.go.dev")
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Errorf("errors.Is(err, context.DeadlineExceeded) = false; want = true")
+	}
+
+	_, err = rCancelled.LookupHost(context.Background(), "test.go.dev")
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("errors.Is(err, context.Canceled) = false; want = true")
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err = goResolver.LookupHost(ctx, "text.go.dev")
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("errors.Is(err, context.Canceled) = false; want = true")
+	}
+}

src/net/net.go

@@ -627,6 +627,8 @@ type notFoundError struct{ s string }
 
 func (e *notFoundError) Error() string { return e.s }
 
+// temporaryError is an error type that implements the [Error] interface.
+// It returns true from the Temporary method.
 type temporaryError struct{ s string }
 
 func (e *temporaryError) Error() string   { return e.s }