![Cian Ruane](/assets/img/avatar_default.png)
The link was missing the /pkg/ prefix.
Fixes #62034.
Change-Id: I96c43f06621e30241e140948129e90f0bd5f8d13
GitHub-Last-Rev: c1e7413f76
GitHub-Pull-Request: golang/go#62040
Reviewed-on: https://go-review.googlesource.com/c/go/+/519575
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Bryan Mills <bcmills@google.com>
8.8 KiB
title | layout |
---|---|
Go, Backwards Compatibility, and GODEBUG | article |
Introduction
Go's emphasis on backwards compatibility is one of its key strengths. There are, however, times when we cannot maintain complete compatibility. If code depends on buggy (including insecure) behavior, then fixing the bug will break that code. New features can also have similar impacts: enabling the HTTP/2 use by the HTTP client broke programs connecting to servers with buggy HTTP/2 implementations. These kinds of changes are unavoidable and permitted by the Go 1 compatibility rules. Even so, Go provides a mechanism called GODEBUG to reduce the impact such changes have on Go developers using newer toolchains to compile old code.
A GODEBUG setting is a key=value
pair
that controls the execution of certain parts of a Go program.
The environment variable GODEBUG
can hold a comma-separated list of these settings.
For example, if a Go program is running in an environment that contains
GODEBUG=http2client=0,http2server=0
then that Go program will disable the use of HTTP/2 by default in both
the HTTP client and the HTTP server.
It is also possible to set the default GODEBUG
for a given program
(discussed below).
When preparing any change that is permitted by Go 1 compatibility but may nonetheless break some existing programs, we first engineer the change to keep as many existing programs working as possible. For the remaining programs, we define a new GODEBUG setting that allows individual programs to opt back in to the old behavior. A GODEBUG setting may not be added if doing so is infeasible, but that should be extremely rare.
GODEBUG settings added for compatibility will be maintained
for a minimum of two years (four Go releases).
Some, such as http2client
and http2server
,
will be maintained much longer, even indefinitely.
When possible, each GODEBUG setting has an associated
runtime/metrics counter
named /godebug/non-default-behavior/<name>:events
that counts the number of times a particular program's
behavior has changed based on a non-default value
for that setting.
For example, when GODEBUG=http2client=0
is set,
/godebug/non-default-behavior/http2client:events
counts the number of HTTP transports that the program
has configured without HTTP/2 support.
Default GODEBUG Values
When a GODEBUG setting is not listed in the environment variable,
its value is derived from three sources:
the defaults for the Go toolchain used to build the program,
amended to match the Go version listed in go.mod
,
and then overridden by explicit //go:debug
lines in the program.
The GODEBUG History gives the exact defaults for each Go toolchain version.
For example, Go 1.21 introduces the panicnil
setting,
controlling whether panic(nil)
is allowed;
it defaults to panicnil=0
, making panic(nil)
a run-time error.
Using panicnil=1
restores the behavior of Go 1.20 and earlier.
When compiling a work module or workspace that declares
an older Go version, the Go toolchain amends its defaults
to match that older Go version as closely as possible.
For example, when a Go 1.21 toolchain compiles a program,
if the work module's go.mod
or the workspace's go.work
says go
1.20
, then the program defaults to panicnil=1
,
matching Go 1.20 instead of Go 1.21.
Because this method of setting GODEBUG defaults was introduced only in Go 1.21, programs listing versions of Go earlier than Go 1.20 are configured to match Go 1.20, not the older version.
To override these defaults, a main package's source files
can include one or more //go:debug
directives at the top of the file
(preceding the package
statement).
Continuing the panicnil
example, if the module or workspace is updated
to say go
1.21
, the program can opt back into the old panic(nil)
behavior by including this directive:
//go:debug panicnil=1
Starting in Go 1.21, the Go toolchain treats a //go:debug
directive
with an unrecognized GODEBUG setting as an invalid program.
Programs with more than one //go:debug
line for a given setting
are also treated as invalid.
(Older toolchains ignore //go:debug
directives entirely.)
The defaults that will be compiled into a main package are reported by the command:
{{raw go list -f '{{.DefaultGODEBUG}}' my/main/package
}}
Only differences from the base Go toolchain defaults are reported.
When testing a package, //go:debug
lines in the *_test.go
files are treated as directives for the test's main package.
In any other context, //go:debug
lines are ignored by the toolchain;
go
vet
reports such lines as misplaced.
GODEBUG History
This section documents the GODEBUG settings introduced and removed in each major Go release for compatibility reasons. Packages or programs may define additional settings for internal debugging purposes; for example, see the runtime documentation and the go command documentation.
Go 1.22
Go 1.22 adds a configurable limit to control the maximum acceptable RSA key size
that can be used in TLS handshakes, controlled by the tlsmaxrsasize
setting.
The default is tlsmaxrsasize=8192, limiting RSA to 8192-bit keys. To avoid
denial of service attacks, this setting and default was backported to Go
1.19.13, Go 1.20.8, and Go 1.21.1.
Go 1.22 made it an error for a request or response read by a net/http
client or server to have an empty Content-Length header.
This behavior is controlled by the httplaxcontentlength
setting.
Go 1.21
Go 1.21 made it a run-time error to call panic
with a nil interface value,
controlled by the panicnil
setting.
Go 1.21 made it an error for html/template actions to appear inside of an ECMAScript 6
template literal, controlled by the
jstmpllitinterp
setting.
This behavior was backported to Go 1.19.8+ and Go 1.20.3+.
Go 1.21 introduced a limit on the maximum number of MIME headers and multipart
forms, controlled by the
multipartmaxheaders
and multipartmaxparts
settings
respectively.
This behavior was backported to Go 1.19.8+ and Go 1.20.3+.
Go 1.21 adds the support of Multipath TCP but it is only used if the application
explicitly asked for it. This behavior can be controlled by the
multipathtcp
setting.
There is no plan to remove any of these settings.
Go 1.20
Go 1.20 introduced support for rejecting insecure paths in tar and zip archives,
controlled by the tarinsecurepath
setting
and the zipinsecurepath
setting.
These default to tarinsecurepath=1
and zipinsecurepath=1
,
preserving the behavior of earlier versions of Go.
A future version of Go may change the defaults to
tarinsecurepath=0
and zipinsecurepath=0
.
Go 1.20 introduced automatic seeding of the
math/rand
global random number generator,
controlled by the randautoseed
setting.
Go 1.20 introduced the concept of fallback roots for use during certificate verification,
controlled by the x509usefallbackroots
setting.
Go 1.20 removed the preinstalled .a
files for the standard library
from the Go distribution.
Installations now build and cache the standard library like
packages in other modules.
The installgoroot
setting
restores the installation and use of preinstalled .a
files.
There is no plan to remove any of these settings.
Go 1.19
Go 1.19 made it an error for path lookups to resolve to binaries in the current directory,
controlled by the execerrdot
setting.
There is no plan to remove this setting.
Go 1.18
Go 1.18 removed support for SHA1 in most X.509 certificates,
controlled by the x509sha1
setting.
This setting will be removed in a future release, Go 1.22 at the earliest.
Go 1.10
Go 1.10 changed how build caching worked and added test caching, along
with the gocacheverify
, gocachehash
, and gocachetest
settings.
There is no plan to remove these settings.
Go 1.6
Go 1.6 introduced transparent support for HTTP/2,
controlled by the http2client
, http2server
, and http2debug
settings.
There is no plan to remove these settings.
Go 1.5
Go 1.5 introduced a pure Go DNS resolver,
controlled by the netdns
setting.
There is no plan to remove this setting.