Go 1.24 Deep Dive: Generic Type Aliases, os.Root, and Post-Quantum Crypto

11.02.2025 — golang, go1.24, generics, security, crypto, performance, tooling — 11 min read

Go 1.24 shipped on February 11, 2025. It is a small language release and a large standard-library and tooling release, which is the shape of most modern Go versions. The one language change worth knowing is generic type aliases. Everything else that matters is in the library and the toolchain: a filesystem API that finally makes path traversal safe by construction, weak pointers and a better finalizer, post-quantum key exchange, a benchmark loop that stops lying to you, and tool dependencies tracked in go.mod instead of a hack file.

One correction up front, because it is a common mix-up: range-over-function iterators and the iter package were Go 1.23, not 1.24. Go 1.24 builds on them by adding iterator-returning helpers to strings and bytes, but the language feature itself already existed. This post covers what is actually new in 1.24, with signatures I checked against the release notes and package docs so the examples compile.

Language: generic type aliases

Go has had generics since 1.18 and type aliases since 1.9, but until now you could not combine them. A type alias could not take type parameters. Go 1.24 removes that restriction, which closes a real gap when you are refactoring or presenting a cleaner name for a parameterized type.

// Now valid in Go 1.24:
type Set[T comparable] = map[T]struct{}
type Handler[Req, Resp any] = func(context.Context, Req) (Resp, error)

// The alias is interchangeable with the underlying type, so this is fine:
var users Set[string] = map[string]struct{}{"alice": {}}

The most practical use is migration. When you move a generic type to a new package, you can leave a parameterized alias behind so existing callers keep compiling while you move them over.

// package newpkg (the real definition)
type Cache[K comparable, V any] struct { /* ... */ }

// package oldpkg (compatibility shim)
type Cache[K comparable, V any] = newpkg.Cache[K, V]

There is a temporary escape hatch, GOEXPERIMENT=noaliastypeparams, if a tool cannot handle the new form yet. It is going away in Go 1.25, so treat the feature as permanent.

os.Root: path traversal safety by construction

This is the change I would adopt first in any service that touches user-supplied paths. Historically, if a request asked for uploads/{name}, you had to sanitize name yourself and hope you caught every ../, every absolute path, and every symlink that pointed out of the directory. People get this wrong constantly, and it is a classic path-traversal vulnerability.

os.OpenRoot opens a directory and returns an *os.Root whose operations cannot escape it. The confinement is enforced by the OS-level API, including against symlinks, not by string checks you have to trust.

root, err := os.OpenRoot("/srv/uploads")
if err != nil {
    return err
}
defer root.Close()

f, err := root.Open(userSuppliedName) // relative to /srv/uploads
if err != nil {
    return err // includes the case where the path tried to escape
}
defer f.Close()

os.OpenRoot("/srv/uploads")
             │
             ▼
   root.Open("a/../b.txt")        ──▶  ok, resolves inside /srv/uploads
   root.Open("../../etc/passwd")  ──▶  error, path escapes the root
   root.Open(symlink -> /etc)     ──▶  error, symlink leaves the root

os.Root has the methods you expect: Open, Create, Mkdir, Stat, Lstat, Remove, and FS() to hand an fs.FS to code that wants one. The signatures are the plain os ones minus the ability to walk out of the directory. If you serve files from a per-tenant directory, extract archives, or accept any path from a client, move that code onto os.Root and delete your hand-rolled sanitizer.

weak pointers and runtime.AddCleanup

Two runtime additions make caches and resource cleanup less error-prone.

The new weak package gives you a typed weak pointer. It references an object without keeping it alive, so it is the right tool for a canonicalization map or cache that should not, by itself, prevent collection.

import "weak"

var wp weak.Pointer[Resource] = weak.Make(res)

// Later: get the object back, or nil if it was collected.
if r := wp.Value(); r != nil {
    use(r)
}

runtime.AddCleanup replaces runtime.SetFinalizer for releasing an underlying resource when an object is collected. It is deliberately harder to misuse: you can attach several cleanups to one object, it works on objects in reference cycles, and it does not resurrect the object the way a finalizer can.

type File struct{ fd int }

func open(path string) (*File, error) {
    fd, err := syscall.Open(path, syscall.O_RDONLY, 0)
    if err != nil {
        return nil, err
    }
    f := &File{fd: fd}
    // If f becomes unreachable without Close being called, close the fd.
    runtime.AddCleanup(f, func(fd int) { syscall.Close(fd) }, f.fd)
    return f, nil
}

The signature is runtime.AddCleanup[T, S any](ptr *T, cleanup func(S), arg S) Cleanup. The important discipline is unchanged: a cleanup is a backstop, not a substitute for an explicit Close. It runs at an unspecified time and may not run before program exit.

strings and bytes iterators

Now that range-over-func exists, strings and bytes return iterators for the common splitting operations, so you can loop without allocating a full slice up front. This matters when you process large inputs and only need one piece at a time.

for line := range strings.Lines(text) {   // each line keeps its trailing \n
    process(line)
}

for field := range strings.FieldsSeq(text) {
    process(field)
}

for part := range strings.SplitSeq(csv, ",") {
    process(part)
}

The full set is Lines, SplitSeq, SplitAfterSeq, FieldsSeq, and FieldsFuncSeq, mirrored in bytes. Reach for the Seq variants over strings.Split when the input is large or you may stop early, and keep Split when you genuinely need the slice.

Related: encoding gained TextAppender and BinaryAppender. If your type implements them, marshaling can append into a caller-provided buffer instead of allocating a fresh slice per call, which helps on hot serialization paths.

encoding/json: omitzero

encoding/json added the omitzero field option. The long-standing omitempty has an awkward definition (empty for it means the type's empty value, which does not do what you want for structs or time.Time). omitzero omits a field when it is the zero value, and it honors an IsZero() bool method if the type has one.

type Event struct {
    Name string    `json:"name"`
    At   time.Time `json:"at,omitzero"` // dropped when the zero time, unlike omitempty
}

Prefer omitzero over omitempty for structs and for types like time.Time where "empty" never behaved sensibly.

Crypto: post-quantum, promoted packages, and real FIPS

The 1.24 crypto work is substantial, and it is worth being precise because there is a lot of misinformation about the API.

The new crypto/mlkem package implements ML-KEM (FIPS 203), the standardized post-quantum key-encapsulation mechanism, in the 768 and 1024 parameter sizes. This is key exchange, not signing. One side generates a decapsulation key and shares the public encapsulation key; the other side encapsulates a shared secret and returns the ciphertext.

// Alice generates a keypair and sends the encapsulation key to Bob.
dk, err := mlkem.GenerateKey768()
if err != nil {
    return err
}
encapsulationKey := dk.EncapsulationKey().Bytes()

// Bob derives a shared secret and returns the ciphertext.
ek, err := mlkem.NewEncapsulationKey768(encapsulationKey)
if err != nil {
    return err
}
sharedSecret, ciphertext := ek.Encapsulate()

// Alice recovers the same secret from the ciphertext.
sharedSecret2, err := dk.Decapsulate(ciphertext)
// sharedSecret == sharedSecret2

crypto/hkdf (RFC 5869), crypto/pbkdf2 (RFC 8018), and crypto/sha3 (FIPS 202) also joined the standard library, promoted from golang.org/x/crypto. If you imported those from x/crypto, you can now depend on the standard library instead.

FIPS 140-3 support is real in 1.24, but not the way the internet often claims. There is no crypto/fips package and no fips.Enable() call. Instead, the standard crypto packages contain a validated Go Cryptographic Module (v1.0.0), and you select FIPS mode with the GOFIPS140 build setting or the fips140 GODEBUG at runtime. Your code keeps calling the normal crypto/* APIs.

# Build against the validated module and run in FIPS mode:
GOFIPS140=v1.0.0 go build ./...
GODEBUG=fips140=on ./yourservice

For the record, and because the old version of this post claimed otherwise: there is no crypto/aes256 package (use crypto/aes with crypto/cipher), and Go 1.24 did not add math.Tau, math.Phi, math.FMA, or built-in HTTP/3 to net/http.

Testing: b.Loop and synctest

Benchmarks got a real correctness fix. The classic for i := 0; i < b.N; i++ loop has two problems: the compiler can optimize away a body whose result is unused, and any setup you do inside the loop is counted in the measurement. b.Loop() fixes both. It keeps the body from being optimized away and only times the loop itself, so setup before the loop and teardown after are not measured.

func BenchmarkEncode(b *testing.B) {
    data := makeLargeInput() // not measured
    b.ResetTimer()
    for b.Loop() {
        _ = Encode(data) // measured, and not optimized away
    }
}

Prefer for b.Loop() over the b.N form in new benchmarks.

Go 1.24 also introduced testing/synctest as an experiment for testing concurrent, time-dependent code with a fake clock, enabled with GOEXPERIMENT=synctest and exposing synctest.Run and synctest.Wait. It graduated to a stable testing/synctest package in Go 1.25, so on 1.24 treat it as a preview.

Runtime and performance

The headline is modest and honest: runtime changes cut CPU overhead by about 2 to 3 percent on average across a suite of benchmarks. You get this by rebuilding, with no code changes. Three pieces drive it.

The built-in map now uses a Swiss Tables design, which improves lookup and iteration on large maps. The small-object allocator is more efficient, which helps allocation-heavy code. And there is a new runtime-internal mutex that reduces contention overhead. Each has a GOEXPERIMENT opt-out (noswissmap, nospinbitmutex) if you need to isolate a regression, but the defaults are the point.

Tooling

Tool dependencies in go.mod

For years, the way to pin a code-generation or lint tool to a module was the tools.go blank-import trick. Go 1.24 replaces it with a first-class tool directive in go.mod.

go get -tool golang.org/x/tools/cmd/stringer   # adds a tool directive
go tool stringer -type=Pill                     # runs the pinned version

The version lives in go.mod like any other dependency, go tool runs it, and executables from go run and go tool are now cached, so repeated runs are fast. You can delete tools.go.

Build provenance and JSON output

go build now stamps the main module's version into runtime/debug.BuildInfo.Main.Version from the VCS tag or commit, with a +dirty suffix when the tree has uncommitted changes. That means go version -m ./binary tells you exactly what built it, which is useful for incident response and SBOMs. Disable it with -buildvcs=false if a build environment lacks VCS metadata.

Both go build/go install -json and the build phase of go test -json now emit structured JSON, which makes CI output easier to parse. If a tool depended on the old plain-text go test build failures, revert with GODEBUG=gotestjsonbuildtext=1.

Private modules and vet

GOAUTH gives you a configurable way to authenticate fetches of private modules, beyond .netrc. And go vet sharpened up: a new tests analyzer catches malformed test, fuzz, benchmark, and example declarations; printf now flags a non-constant format string like fmt.Printf(s); buildtag rejects invalid version constraints such as go1.23.1; and copylock catches a sync.Locker copied through a 3-clause for loop variable.

For cgo users, #cgo noescape and #cgo nocallback annotations let you tell the compiler that a C function does not retain Go pointers or call back into Go, which unlocks better optimization at the boundary.

Upgrade notes

Rebuild and run your suite. The runtime changes are transparent, but rebuilding is how you get the 2 to 3 percent and the Swiss Tables map.
Move any code that opens user-supplied paths onto os.Root and delete the hand-rolled path sanitizer.
Replace tools.go with go get -tool and go tool. Drop the blank-import file.
Convert new and hot benchmarks to for b.Loop().
Switch omitempty to omitzero for structs and time.Time fields where the old behavior never worked.
If you vendored hkdf, pbkdf2, or sha3 from x/crypto, move to the standard library packages.
Let go vet run in CI and clear the new tests and printf findings.

Closing thoughts

Go 1.24 is a practical release. os.Root removes a whole vulnerability class, tool directives retire an old workaround, b.Loop makes your benchmarks honest, and you get a couple percent of CPU back for free. The crypto additions matter if you care about post-quantum readiness or FIPS, and they are worth learning correctly, because the common secondhand descriptions of the FIPS mechanism are wrong. If you adopt one thing this week, make it os.Root in any service that handles paths from the outside world.