From b8b3208fb3c28b7fdf531264ca51f771c844a6ef Mon Sep 17 00:00:00 2001 From: Brad Fitzpatrick Date: Tue, 10 Nov 2026 21:30:36 +0000 Subject: [PATCH] util/eventbus/eventbuscheck: add whole-program T vs *T event check The eventbus routes events by exact type, so a subscriber of *T never sees a T. Add a test that type-checks the module for linux, windows and darwin and fails if any event type is used with eventbus or eventbustest both by value and by pointer. To keep memory use down, it drops function bodies outside the packages that import those. It skips in race builds because of a go/types data race, golang/go#81122. Updates #22307 Change-Id: Ia7486c43936f367f8767ad9c8750faa9b6bdf8f0 Signed-off-by: Brad Fitzpatrick --- util/eventbus/eventbuscheck/eventbuscheck.go | 304 ++++++++++++++++++ .../eventbuscheck/eventbuscheck_test.go | 66 ++++ .../eventbuscheck/testdata/mixed/mixed.go | 55 ++++ 3 files changed, 425 insertions(+) create mode 100644 util/eventbus/eventbuscheck/eventbuscheck.go create mode 100644 util/eventbus/eventbuscheck/eventbuscheck_test.go create mode 100644 util/eventbus/eventbuscheck/testdata/mixed/mixed.go diff --git a/util/eventbus/eventbuscheck/eventbuscheck.go b/util/eventbus/eventbuscheck/eventbuscheck.go new file mode 100644 index 000000000..e27fa1ff9 --- /dev/null +++ b/util/eventbus/eventbuscheck/eventbuscheck.go @@ -0,0 +1,304 @@ +// Copyright (c) Tailscale Inc & contributors +// SPDX-License-Identifier: BSD-3-Clause + +// Package eventbuscheck statically finds event types that are used with an +// [tailscale.com/util/eventbus.Bus] both by value and by pointer. +// +// The eventbus routes events by exact type, so a subscriber of *T never sees +// events published as T. Pointer event types are fine, but a program must use +// each event type in only one form. Because the publisher and subscriber of a +// type are often in packages that don't import each other, this is a +// whole-program check rather than a vet analyzer. +package eventbuscheck + +import ( + "cmp" + "fmt" + "go/ast" + "go/parser" + "go/token" + "go/types" + "os" + "slices" + "strings" + + "golang.org/x/tools/go/packages" + "tailscale.com/util/set" +) + +const ( + eventbusPath = "tailscale.com/util/eventbus" + eventbustestPath = "tailscale.com/util/eventbus/eventbustest" +) + +// typeArgFuncs are the generic functions whose first type argument is an event +// type. +var typeArgFuncs = map[string]bool{ + eventbusPath + ".Publish": true, + eventbusPath + ".Subscribe": true, + eventbusPath + ".SubscribeFunc": true, + eventbustestPath + ".Inject": true, + eventbustestPath + ".Type": true, + eventbustestPath + ".EqualTo": true, +} + +// filterFuncs are the functions whose variadic arguments are event filter +// funcs whose first parameter is an event type. +var filterFuncs = map[string]bool{ + eventbustestPath + ".Expect": true, + eventbustestPath + ".ExpectExactly": true, +} + +// Site is a use of an event type in an eventbus call. +type Site struct { + Pos token.Position + Func string // name of the eventbus or eventbustest func, like "eventbus.Publish" + Type string // event type, fully qualified, like "*tailscale.com/tailcfg.ClientVersion" +} + +// Mismatch is an event type that is used both by value and by pointer. +type Mismatch struct { + Type string // the non-pointer form of the event type + Sites []Site // all uses of the type in either form, sorted by position +} + +func (m Mismatch) String() string { + var sb strings.Builder + fmt.Fprintf(&sb, "eventbus event type %s is used both by value and by pointer:", m.Type) + for _, s := range m.Sites { + fmt.Fprintf(&sb, "\n\t%s: %s[%s]", s.Pos, s.Func, s.Type) + } + return sb.String() +} + +// Check loads the packages matching patterns from dir, along with their tests +// and dependencies, once for each GOOS in goos with GOARCH=amd64. It returns +// the event types used both by value and by pointer across all of them. +func Check(dir string, goos []string, patterns ...string) ([]Mismatch, error) { + var sites []Site + for _, g := range goos { + s, err := loadSites(dir, g, patterns) + if err != nil { + return nil, fmt.Errorf("GOOS=%s: %w", g, err) + } + sites = append(sites, s...) + } + return mismatches(sites), nil +} + +// loadSites returns the uses of event types in the packages matching +// patterns and all their dependencies, type-checked from source for goos. +func loadSites(dir, goos string, patterns []string) ([]Site, error) { + env := append(os.Environ(), "GOOS="+goos, "GOARCH=amd64", "CGO_ENABLED=0") + + // Find the packages that import eventbus or eventbustest, which are the + // only ones that can use an event type, without type-checking anything. + pkgs, err := packages.Load(&packages.Config{ + Mode: packages.NeedName | packages.NeedCompiledGoFiles | packages.NeedImports | packages.NeedDeps, + Dir: dir, + Tests: true, + Env: env, + }, patterns...) + if err != nil { + return nil, err + } + usesBus := set.Set[string]{} // IDs of packages that import eventbus or eventbustest + keepBodies := set.Set[string]{} // filenames of the files in usesBus packages + packages.Visit(pkgs, nil, func(pkg *packages.Package) { + if pkg.Imports[eventbusPath] == nil && pkg.Imports[eventbustestPath] == nil { + return + } + if pkg.Name == "main" && strings.HasSuffix(pkg.PkgPath, ".test") { + // A generated test main, whose files are in the build + // cache and have no event types. + return + } + usesBus.Add(pkg.ID) + keepBodies.AddSlice(pkg.CompiledGoFiles) + }) + + // Type-check everything, but drop the function bodies from files that + // can't use an event type. The other packages only need their + // declarations, and their bodies are most of the memory use. + pkgs, err = packages.Load(&packages.Config{ + Mode: packages.LoadAllSyntax, + Dir: dir, + Tests: true, + Env: env, + ParseFile: func(fset *token.FileSet, filename string, src []byte) (*ast.File, error) { + if keepBodies.Contains(filename) { + return parser.ParseFile(fset, filename, src, parser.AllErrors|parser.ParseComments|parser.SkipObjectResolution) + } + f, err := parser.ParseFile(fset, filename, src, parser.SkipObjectResolution) + if f != nil { + for _, d := range f.Decls { + if fd, ok := d.(*ast.FuncDecl); ok { + fd.Body = nil + } + } + } + return f, err + }, + }, patterns...) + if err != nil { + return nil, err + } + var errs []string + var sites []Site + packages.Visit(pkgs, nil, func(pkg *packages.Package) { + if !usesBus.Contains(pkg.ID) { + // Errors are expected here, like imports only used by the + // dropped bodies. + return + } + for _, e := range pkg.Errors { + errs = append(errs, e.Error()) + } + if pkg.TypesInfo == nil { + return + } + for _, f := range pkg.Syntax { + sites = append(sites, fileSites(pkg.Fset, pkg.TypesInfo, f)...) + } + }) + if len(errs) > 0 { + return nil, fmt.Errorf("package errors:\n%s", strings.Join(errs, "\n")) + } + return sites, nil +} + +// fileSites returns the uses of event types in f. +func fileSites(fset *token.FileSet, info *types.Info, f *ast.File) []Site { + var sites []Site + add := func(pos token.Pos, fn *types.Func, t types.Type) { + if containsTypeParam(t) { + // A generic wrapper like eventbustest.Inject. Its callers' + // instantiations are recorded at their own call sites. + return + } + sites = append(sites, Site{ + Pos: fset.Position(pos), + Func: fn.Pkg().Name() + "." + fn.Name(), + Type: types.TypeString(t, nil), + }) + } + ast.Inspect(f, func(n ast.Node) bool { + switch n := n.(type) { + case *ast.Ident: + fn := eventbusFunc(info, n) + if fn == nil || !typeArgFuncs[fn.FullName()] { + return true + } + if inst, ok := info.Instances[n]; ok && inst.TypeArgs.Len() > 0 { + add(n.Pos(), fn, inst.TypeArgs.At(0)) + } + case *ast.CallExpr: + fn := eventbusFunc(info, calleeIdent(n.Fun)) + if fn == nil || !filterFuncs[fn.FullName()] { + return true + } + for _, arg := range n.Args { + if c, ok := arg.(*ast.CallExpr); ok && eventbusFunc(info, calleeIdent(c.Fun)) != nil { + // Already recorded as a type argument of + // eventbustest.Type or EqualTo. + continue + } + sig, ok := info.TypeOf(arg).(*types.Signature) + if !ok || sig.Params().Len() == 0 { + continue + } + add(arg.Pos(), fn, sig.Params().At(0).Type()) + } + } + return true + }) + return sites +} + +// calleeIdent returns the identifier naming the function in a call's Fun +// expression, or nil if there isn't one. +func calleeIdent(fun ast.Expr) *ast.Ident { + for { + switch e := fun.(type) { + case *ast.Ident: + return e + case *ast.SelectorExpr: + return e.Sel + case *ast.IndexExpr: + fun = e.X + case *ast.IndexListExpr: + fun = e.X + case *ast.ParenExpr: + fun = e.X + default: + return nil + } + } +} + +// eventbusFunc returns the package-level func in the eventbus or eventbustest +// package that id refers to, or nil if it doesn't refer to one. +func eventbusFunc(info *types.Info, id *ast.Ident) *types.Func { + if id == nil { + return nil + } + fn, ok := info.Uses[id].(*types.Func) + if !ok || fn.Pkg() == nil { + return nil + } + if p := fn.Pkg().Path(); p != eventbusPath && p != eventbustestPath { + return nil + } + if fn.Signature().Recv() != nil { + return nil + } + return fn +} + +func containsTypeParam(t types.Type) bool { + if p, ok := t.(*types.Pointer); ok { + t = p.Elem() + } + _, ok := t.(*types.TypeParam) + return ok +} + +// mismatches groups sites by the non-pointer form of their event type and +// returns the groups that use both forms. +func mismatches(sites []Site) []Mismatch { + type key struct { + pos token.Position + typ string + } + seen := map[key]bool{} + byBase := map[string][]Site{} + for _, s := range sites { + // The same file is loaded multiple times: for each GOOS, and as both + // a package and its test variant. + k := key{s.Pos, s.Type} + if seen[k] { + continue + } + seen[k] = true + base := strings.TrimPrefix(s.Type, "*") + byBase[base] = append(byBase[base], s) + } + var ret []Mismatch + for base, ss := range byBase { + hasValue := slices.ContainsFunc(ss, func(s Site) bool { return s.Type == base }) + hasPtr := slices.ContainsFunc(ss, func(s Site) bool { return s.Type != base }) + if !hasValue || !hasPtr { + continue + } + slices.SortFunc(ss, func(a, b Site) int { + return cmp.Or( + cmp.Compare(a.Pos.Filename, b.Pos.Filename), + cmp.Compare(a.Pos.Line, b.Pos.Line), + cmp.Compare(a.Pos.Column, b.Pos.Column), + ) + }) + ret = append(ret, Mismatch{Type: base, Sites: ss}) + } + slices.SortFunc(ret, func(a, b Mismatch) int { return cmp.Compare(a.Type, b.Type) }) + return ret +} diff --git a/util/eventbus/eventbuscheck/eventbuscheck_test.go b/util/eventbus/eventbuscheck/eventbuscheck_test.go new file mode 100644 index 000000000..6641cf91a --- /dev/null +++ b/util/eventbus/eventbuscheck/eventbuscheck_test.go @@ -0,0 +1,66 @@ +// Copyright (c) Tailscale Inc & contributors +// SPDX-License-Identifier: BSD-3-Clause + +package eventbuscheck + +import ( + "path/filepath" + "runtime/debug" + "slices" + "testing" + + "tailscale.com/version" +) + +// skipIfRace skips the test in race builds, where concurrent type-checking in +// [packages.Load] trips a data race in go/types. See golang/go#81122. +func skipIfRace(t *testing.T) { + if version.IsRace() { + t.Skip("skipping in race builds; see golang/go#81122") + } +} + +// TestNoPointerValueMismatch checks that no event type in this module is used +// with the eventbus both by value and by pointer. +func TestNoPointerValueMismatch(t *testing.T) { + skipIfRace(t) + + // Collect garbage more often while type-checking the whole module, which + // lowers its peak memory use from about 2 GB to about 1.5 GB. + defer debug.SetGCPercent(debug.SetGCPercent(25)) + + root, err := filepath.Abs("../../..") + if err != nil { + t.Fatal(err) + } + ms, err := Check(root, []string{"linux", "windows", "darwin"}, "./...") + if err != nil { + t.Fatal(err) + } + for _, m := range ms { + t.Error(m) + } +} + +func TestCheckTestdata(t *testing.T) { + skipIfRace(t) + ms, err := Check(".", []string{"linux"}, "./testdata/mixed") + if err != nil { + t.Fatal(err) + } + const pkg = "tailscale.com/util/eventbus/eventbuscheck/testdata/mixed." + var got []string + for _, m := range ms { + got = append(got, m.Type) + t.Logf("%v", m) + } + want := []string{ + pkg + "ExpectPtr", + pkg + "InjectPtr", + pkg + "PubBoth", + pkg + "PubValueSubPtr", + } + if !slices.Equal(got, want) { + t.Errorf("mismatched types:\n got %q\nwant %q", got, want) + } +} diff --git a/util/eventbus/eventbuscheck/testdata/mixed/mixed.go b/util/eventbus/eventbuscheck/testdata/mixed/mixed.go new file mode 100644 index 000000000..7f5252c67 --- /dev/null +++ b/util/eventbus/eventbuscheck/testdata/mixed/mixed.go @@ -0,0 +1,55 @@ +// Copyright (c) Tailscale Inc & contributors +// SPDX-License-Identifier: BSD-3-Clause + +// Package mixed uses event types in ways that eventbuscheck should and should +// not report. +package mixed + +import ( + "testing" + + "tailscale.com/util/eventbus" + "tailscale.com/util/eventbus/eventbustest" +) + +// PubValueSubPtr is published by value but subscribed by pointer. +type PubValueSubPtr struct{} + +// PubBoth is published both by value and by pointer. +type PubBoth struct{} + +// InjectPtr is published by value but injected by pointer in a test. +type InjectPtr struct{} + +// ExpectPtr is published by value but expected by pointer in a test. +type ExpectPtr struct{} + +// PtrOnly is consistently used by pointer, which is fine. +type PtrOnly struct{} + +// ValueOnly is consistently used by value, which is fine. +type ValueOnly struct{} + +func onPubValueSubPtr(*PubValueSubPtr) {} + +func use(c *eventbus.Client, t *testing.T, inj *eventbustest.Injector, tw *eventbustest.Watcher) { + eventbus.Publish[PubValueSubPtr](c) + eventbus.SubscribeFunc(c, onPubValueSubPtr) + + eventbus.Publish[PubBoth](c) + eventbus.Publish[*PubBoth](c) + + eventbus.Publish[InjectPtr](c) + eventbustest.Inject(inj, &InjectPtr{}) + + eventbus.Publish[ExpectPtr](c) + eventbustest.Expect(tw, func(*ExpectPtr) {}) + + eventbus.Publish[*PtrOnly](c) + eventbus.Subscribe[*PtrOnly](c) + eventbustest.Expect(tw, eventbustest.Type[*PtrOnly]()) + + eventbus.Publish[ValueOnly](c) + eventbus.SubscribeFunc(c, func(ValueOnly) {}) + eventbustest.Expect(tw, eventbustest.EqualTo(ValueOnly{})) +}