From 06c847e1184d477cfb622ff6710b48848bf0ffcf Mon Sep 17 00:00:00 2001 From: Ethan Lee Date: Wed, 11 Mar 2026 21:17:12 +0000 Subject: internal/api: implement package symbols endpoint - Introduce a new ServePackageSymbols handler that utilizes the new db.GetSymbols method. - Consolidated module resolution logic shared by ServePackages into resolveModulePath. - Updated Datasource with GetSymbols, which provides a more efficient way to retrieve all symbols for a package at a given version and build context. This differs from the existing getPackageSymbols, since that will return symbols for the latest release/compatible version. - Refactored packageSymbolQueryJoin into a generic helper by removing hardcoded version filters. This allows GetSymbols to query for any specific version, while getPackageSymbols was updated to explicitly include release-only filters to preserve its existing behavior. - GetSymbols still utilizes the same underlying packageSymbolQueryJoin, but it will also attempt to match the most relevant BuildContext for the query. It will also provide a mapping of parent and child symbols. Change-Id: Ib18d2511d24ac6bc5b75c7b3809c4ce126245036 Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/754864 Auto-Submit: Ethan Lee kokoro-CI: kokoro Reviewed-by: Jonathan Amsterdam LUCI-TryBot-Result: Go LUCI --- internal/api/api.go | 185 +++++++++++++++++++++++++++++------------------ internal/api/api_test.go | 127 +++++++++++++++++++++++++++++++- 2 files changed, 238 insertions(+), 74 deletions(-) (limited to 'internal/api') diff --git a/internal/api/api.go b/internal/api/api.go index 4f4fcf7b..edd758e1 100644 --- a/internal/api/api.go +++ b/internal/api/api.go @@ -42,37 +42,15 @@ func ServePackage(w http.ResponseWriter, r *http.Request, ds internal.DataSource return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil) } - requestedVersion := params.Version - if requestedVersion == "" { - requestedVersion = version.Latest - } - - var um *internal.UnitMeta - modulePath := params.Module - if modulePath == "" { - // Handle potential ambiguity if module is not specified. - candidates := internal.CandidateModulePaths(pkgPath) - var validCandidates []Candidate - for _, mp := range candidates { - // Check if this module actually exists and contains the package at the requested version. - if m, err := ds.GetUnitMeta(r.Context(), pkgPath, mp, requestedVersion); err == nil { - um = m - validCandidates = append(validCandidates, Candidate{ - ModulePath: mp, - PackagePath: pkgPath, - }) - } else if !errors.Is(err, derrors.NotFound) { - return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil) - } - } - - if len(validCandidates) > 1 { - return serveErrorJSON(w, http.StatusBadRequest, "ambiguous package path", validCandidates) - } - if len(validCandidates) == 0 { - return serveErrorJSON(w, http.StatusNotFound, "package not found", nil) + um, candidates, err := resolveModulePath(r, ds, pkgPath, params.Module, params.Version) + if err != nil { + if errors.Is(err, derrors.NotFound) { + return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil) } - modulePath = validCandidates[0].ModulePath + return err + } + if len(candidates) > 0 { + return serveErrorJSON(w, http.StatusBadRequest, "ambiguous package path", candidates) } // Use GetUnit to get the requested data. @@ -88,44 +66,9 @@ func ServePackage(w http.ResponseWriter, r *http.Request, ds internal.DataSource } bc := internal.BuildContext{GOOS: params.GOOS, GOARCH: params.GOARCH} - var unit *internal.Unit - if um != nil { - var err error - unit, err = ds.GetUnit(r.Context(), um, fs, bc) - if err != nil { - return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil) - } - } else if modulePath != "" && modulePath != internal.UnknownModulePath && !needsResolution(requestedVersion) { - // This block is reachable if the user explicitly provided a module path and a - // concrete version in the query parameters, skipping the candidate search. - um = &internal.UnitMeta{ - Path: pkgPath, - ModuleInfo: internal.ModuleInfo{ - ModulePath: modulePath, - Version: requestedVersion, - }, - } - var err error - unit, err = ds.GetUnit(r.Context(), um, fs, bc) - if err != nil && !errors.Is(err, derrors.NotFound) { - return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil) - } - } - - if unit == nil { - // Fallback: Resolve the version or find the module using GetUnitMeta. - var err error - um, err = ds.GetUnitMeta(r.Context(), pkgPath, modulePath, requestedVersion) - if err != nil { - if errors.Is(err, derrors.NotFound) { - return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil) - } - return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil) - } - unit, err = ds.GetUnit(r.Context(), um, fs, bc) - if err != nil { - return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil) - } + unit, err := ds.GetUnit(r.Context(), um, fs, bc) + if err != nil { + return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil) } // Process documentation, including synopsis. @@ -393,9 +336,109 @@ func ServeSearch(w http.ResponseWriter, r *http.Request, ds internal.DataSource) return serveJSON(w, http.StatusOK, resp) } -// needsResolution reports whether the version string is a sentinel like "latest" or "master". -func needsResolution(v string) bool { - return v == version.Latest || v == version.Master || v == version.Main +// ServePackageSymbols handles requests for the v1 package symbols endpoint. +func ServePackageSymbols(w http.ResponseWriter, r *http.Request, ds internal.DataSource) (err error) { + defer derrors.Wrap(&err, "ServePackageSymbols") + + pkgPath := strings.TrimPrefix(r.URL.Path, "/v1/symbols/") + pkgPath = strings.Trim(pkgPath, "/") + if pkgPath == "" { + return serveErrorJSON(w, http.StatusBadRequest, "missing package path", nil) + } + + var params SymbolsParams + if err := ParseParams(r.URL.Query(), ¶ms); err != nil { + return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil) + } + + um, candidates, err := resolveModulePath(r, ds, pkgPath, params.Module, params.Version) + if err != nil { + if errors.Is(err, derrors.NotFound) { + return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil) + } + return err + } + if len(candidates) > 0 { + return serveErrorJSON(w, http.StatusBadRequest, "ambiguous package path", candidates) + } + + bc := internal.BuildContext{GOOS: params.GOOS, GOARCH: params.GOARCH} + syms, err := ds.GetSymbols(r.Context(), pkgPath, um.ModulePath, um.Version, bc) + if err != nil { + if errors.Is(err, derrors.NotFound) { + return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil) + } + return err + } + + limit := params.Limit + if limit <= 0 { + limit = 100 + } + if limit > len(syms) { + limit = len(syms) + } + + var items []Symbol + for _, s := range syms[:limit] { + items = append(items, Symbol{ + ModulePath: um.ModulePath, + Version: um.Version, + Name: s.Name, + Kind: string(s.Kind), + Synopsis: s.Synopsis, + Parent: s.ParentName, + }) + } + + resp := PaginatedResponse[Symbol]{ + Items: items, + Total: len(syms), + } + + return serveJSON(w, http.StatusOK, resp) +} + +// resolveModulePath determines the correct module path for a given package path and version. +// If the module path is not provided, it searches through potential candidate module paths +// derived from the package path. If multiple valid modules contain the package, it returns +// a list of candidates to help the user disambiguate the request. +func resolveModulePath(r *http.Request, ds internal.DataSource, pkgPath, modulePath, requestedVersion string) (*internal.UnitMeta, []Candidate, error) { + if requestedVersion == "" { + requestedVersion = version.Latest + } + if modulePath == "" { + // Handle potential ambiguity if module is not specified. + candidates := internal.CandidateModulePaths(pkgPath) + var validCandidates []Candidate + var foundUM *internal.UnitMeta + for _, mp := range candidates { + // Check if this module actually exists and contains the package at the requested version. + if m, err := ds.GetUnitMeta(r.Context(), pkgPath, mp, requestedVersion); err == nil { + foundUM = m + validCandidates = append(validCandidates, Candidate{ + ModulePath: mp, + PackagePath: pkgPath, + }) + } else if !errors.Is(err, derrors.NotFound) { + return nil, nil, err + } + } + + if len(validCandidates) > 1 { + return nil, validCandidates, nil + } + if len(validCandidates) == 0 { + return nil, nil, derrors.NotFound + } + return foundUM, nil, nil + } + + um, err := ds.GetUnitMeta(r.Context(), pkgPath, modulePath, requestedVersion) + if err != nil { + return nil, nil, err + } + return um, nil, nil } func serveJSON(w http.ResponseWriter, status int, data any) error { diff --git a/internal/api/api_test.go b/internal/api/api_test.go index 595a3d25..50c11327 100644 --- a/internal/api/api_test.go +++ b/internal/api/api_test.go @@ -289,7 +289,7 @@ func TestServeModule(t *testing.T) { w := httptest.NewRecorder() err := ServeModule(w, r, ds) - if err != nil { + if err != nil && w.Code != test.wantStatus { t.Fatalf("ServeModule returned error: %v", err) } @@ -357,7 +357,7 @@ func TestServeModuleVersions(t *testing.T) { w := httptest.NewRecorder() err := ServeModuleVersions(w, r, ds) - if err != nil { + if err != nil && w.Code != test.wantStatus { t.Fatalf("ServeModuleVersions returned error: %v", err) } @@ -413,7 +413,7 @@ func TestServeModulePackages(t *testing.T) { w := httptest.NewRecorder() err := ServeModulePackages(w, r, ds) - if err != nil { + if err != nil && w.Code != test.wantStatus { t.Fatalf("ServeModulePackages returned error: %v", err) } @@ -589,3 +589,124 @@ func TestServeSearchPagination(t *testing.T) { }) } } + +func TestServePackageSymbols(t *testing.T) { + ctx := context.Background() + ds := fakedatasource.New() + + const ( + pkgPath = "example.com/pkg" + modulePath = "example.com" + version = "v1.0.0" + ) + + ds.MustInsertModule(ctx, &internal.Module{ + ModuleInfo: internal.ModuleInfo{ModulePath: modulePath, Version: version}, + Units: []*internal.Unit{{ + UnitMeta: internal.UnitMeta{ + Path: pkgPath, + ModuleInfo: internal.ModuleInfo{ModulePath: modulePath, Version: version}, + Name: "pkg", + }, + Symbols: map[internal.BuildContext][]*internal.Symbol{ + {GOOS: "linux", GOARCH: "amd64"}: { + { + SymbolMeta: internal.SymbolMeta{Name: "LinuxSym", Kind: internal.SymbolKindFunction}, + GOOS: "linux", + GOARCH: "amd64", + }, + { + SymbolMeta: internal.SymbolMeta{Name: "T", Kind: internal.SymbolKindType}, + GOOS: "linux", + GOARCH: "amd64", + Children: []*internal.SymbolMeta{ + {Name: "T.M", Kind: internal.SymbolKindMethod, ParentName: "T"}, + }, + }, + }, + {GOOS: "windows", GOARCH: "amd64"}: { + {SymbolMeta: internal.SymbolMeta{Name: "WindowsSym", Kind: internal.SymbolKindFunction}, GOOS: "windows", GOARCH: "amd64"}, + }, + {GOOS: "js", GOARCH: "wasm"}: { + {SymbolMeta: internal.SymbolMeta{Name: "WasmSym", Kind: internal.SymbolKindFunction}, GOOS: "js", GOARCH: "wasm"}, + }, + }, + }}, + }) + + for _, test := range []struct { + name string + url string + wantStatus int + wantCount int + wantName string // Check name of the first symbol to verify build context + }{ + { + name: "default best match (linux)", + url: "/v1/symbols/example.com/pkg?version=v1.0.0", + wantStatus: http.StatusOK, + wantCount: 2, + wantName: "LinuxSym", + }, + { + name: "explicit linux", + url: "/v1/symbols/example.com/pkg?version=v1.0.0&goos=linux&goarch=amd64", + wantStatus: http.StatusOK, + wantCount: 2, + wantName: "LinuxSym", + }, + { + name: "version latest", + url: "/v1/symbols/example.com/pkg?version=latest", + wantStatus: http.StatusOK, + wantCount: 2, + wantName: "LinuxSym", + }, + { + name: "explicit windows", + url: "/v1/symbols/example.com/pkg?version=v1.0.0&goos=windows&goarch=amd64", + wantStatus: http.StatusOK, + wantCount: 1, + wantName: "WindowsSym", + }, + { + name: "explicit wasm", + url: "/v1/symbols/example.com/pkg?version=v1.0.0&goos=js&goarch=wasm", + wantStatus: http.StatusOK, + wantCount: 1, + wantName: "WasmSym", + }, + { + name: "not found build context", + url: "/v1/symbols/example.com/pkg?version=v1.0.0&goos=darwin&goarch=amd64", + wantStatus: http.StatusNotFound, + }, + } { + t.Run(test.name, func(t *testing.T) { + r := httptest.NewRequest("GET", test.url, nil) + w := httptest.NewRecorder() + + err := ServePackageSymbols(w, r, ds) + if err != nil && w.Code != test.wantStatus { + t.Fatalf("ServePackageSymbols returned error: %v", err) + } + + if w.Code != test.wantStatus { + t.Errorf("status = %d, want %d. Body: %s", w.Code, test.wantStatus, w.Body.String()) + } + + if test.wantStatus == http.StatusOK { + var got PaginatedResponse[Symbol] + if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil { + t.Fatalf("json.Unmarshal: %v", err) + } + if len(got.Items) != test.wantCount { + t.Errorf("count = %d, want %d", len(got.Items), test.wantCount) + } + if test.wantName != "" && got.Items[0].Name != test.wantName { + t.Errorf("first symbol = %q, want %q", got.Items[0].Name, test.wantName) + } + } + }) + } +} -- cgit v1.3