all: document legacy //go:linkname for modules with ≥500 dependents

For #67401.

Change-Id: I7dd28c3b01a1a647f84929d15412aa43ab0089ee
Reviewed-on: https://go-review.googlesource.com/c/go/+/587575
Reviewed-by: Cherry Mui <cherryyz@google.com>
Auto-Submit: Russ Cox <rsc@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

7 files changed, 55 insertions, 23 deletions

diff --git a/src/net/badlinkname.go b/src/net/badlinkname.go
index 0334e834a8..57d6f61794 100644
--- a/src/net/badlinkname.go
+++ b/src/net/badlinkname.go
@@ -13,4 +13,3 @@ import _ "unsafe"
 // in new code.
 
 //go:linkname defaultNS
-//go:linkname isDomainName
diff --git a/src/net/dnsclient.go b/src/net/dnsclient.go
index 7f279d0de4..5f135cc211 100644
--- a/src/net/dnsclient.go
+++ b/src/net/dnsclient.go
@@ -76,6 +76,16 @@ func equalASCIIName(x, y dnsmessage.Name) bool {
 // isDomainName checks if a string is a presentation-format domain name
 // (currently restricted to hostname-compatible "preferred name" LDH labels and
 // SRV-like "underscore labels"; see golang.org/issue/12421).
+//
+// isDomainName should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/sagernet/sing
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname isDomainName
 func isDomainName(s string) bool {
 	// The root domain name is valid. See golang.org/issue/45715.
 	if s == "." {
diff --git a/src/net/http/badlinkname.go b/src/net/http/badlinkname.go
index 93408ecd55..98726b1071 100644
--- a/src/net/http/badlinkname.go
+++ b/src/net/http/badlinkname.go
@@ -20,10 +20,8 @@ import _ "unsafe"
 //go:linkname cloneURLValues
 //go:linkname newBufioReader
 //go:linkname newBufioWriterSize
-//go:linkname parseBasicAuth
 //go:linkname putBufioReader
 //go:linkname putBufioWriter
-//go:linkname readRequest
 
 // The compiler doesn't allow linknames on methods, for good reasons.
 // We use this trick to push linknames of the methods.
diff --git a/src/net/http/request.go b/src/net/http/request.go
index f208b95c46..ecb48a4364 100644
--- a/src/net/http/request.go
+++ b/src/net/http/request.go
@@ -25,6 +25,7 @@ import (
 	"strconv"
 	"strings"
 	"sync"
+	_ "unsafe" // for linkname
 
 	"golang.org/x/net/http/httpguts"
 	"golang.org/x/net/idna"
@@ -986,6 +987,16 @@ func (r *Request) BasicAuth() (username, password string, ok bool) {
 
 // parseBasicAuth parses an HTTP Basic Authentication string.
 // "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" returns ("Aladdin", "open sesame", true).
+//
+// parseBasicAuth should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/sagernet/sing
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname parseBasicAuth
 func parseBasicAuth(auth string) (username, password string, ok bool) {
 	const prefix = "Basic "
 	// Case insensitive prefix match. See Issue 22736.
@@ -1061,6 +1072,15 @@ func ReadRequest(b *bufio.Reader) (*Request, error) {
 	return req, err
 }
 
+// readRequest should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/sagernet/sing
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname readRequest
 func readRequest(b *bufio.Reader) (req *Request, err error) {
 	tp := newTextprotoReader(b)
 	defer putTextprotoReader(tp)
diff --git a/src/net/interface.go b/src/net/interface.go
index 20ac07d31a..74bb4f0e1c 100644
--- a/src/net/interface.go
+++ b/src/net/interface.go
@@ -9,6 +9,7 @@ import (
 	"internal/itoa"
 	"sync"
 	"time"
+	_ "unsafe"
 )
 
 // BUG(mikio): On JS, methods and functions related to
@@ -17,6 +18,16 @@ import (
 // BUG(mikio): On AIX, DragonFly BSD, NetBSD, OpenBSD, Plan 9 and
 // Solaris, the MulticastAddrs method of Interface is not implemented.
 
+// errNoSuchInterface should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/sagernet/sing
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname errNoSuchInterface
+
 var (
 	errInvalidInterface         = errors.New("invalid network interface")
 	errInvalidInterfaceIndex    = errors.New("invalid network interface index")
diff --git a/src/net/url/badlinkname.go b/src/net/url/badlinkname.go
deleted file mode 100644
index 536abe2fa4..0000000000
--- a/src/net/url/badlinkname.go
+++ /dev/null
@@ -1,20 +0,0 @@
-// Copyright 2024 The Go Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-package url
-
-import _ "unsafe"
-
-// As of Go 1.22, the symbols below are found to be pulled via
-// linkname in the wild. We provide a push linkname here, to
-// keep them accessible with pull linknames.
-// This may change in the future. Please do not depend on them
-// in new code.
-
-// The compiler doesn't allow linknames on methods, for good reasons.
-// We use this trick to push linknames of the methods.
-// Do not call them in this package.
-
-//go:linkname badlinkname_URL_setPath net/url.(*URL).setPath
-func badlinkname_URL_setPath(*URL, string) error
diff --git a/src/net/url/url.go b/src/net/url/url.go
index 629b903f9b..7beaef1ba6 100644
--- a/src/net/url/url.go
+++ b/src/net/url/url.go
@@ -17,6 +17,7 @@ import (
 	"slices"
 	"strconv"
 	"strings"
+	_ "unsafe" // for linkname
 )
 
 // Error reports an error and the operation and URL that caused it.
@@ -677,6 +678,16 @@ func parseHost(host string) (string, error) {
 // - setPath("/foo%2fbar") will set Path="/foo/bar" and RawPath="/foo%2fbar"
 // setPath will return an error only if the provided path contains an invalid
 // escaping.
+//
+// setPath should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/sagernet/sing
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname badSetPath net/url.(*URL).setPath
 func (u *URL) setPath(p string) error {
 	path, err := unescape(p, encodePath)
 	if err != nil {
@@ -692,6 +703,9 @@ func (u *URL) setPath(p string) error {
 	return nil
 }
 
+// for linkname because we cannot linkname methods directly
+func badSetPath(*URL, string) error
+
 // EscapedPath returns the escaped form of u.Path.
 // In general there are multiple possible escaped forms of any path.
 // EscapedPath returns u.RawPath when it is a valid escaping of u.Path.