aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--internal/api/api.go185
-rw-r--r--internal/api/api_test.go127
-rw-r--r--internal/datasource.go2
-rw-r--r--internal/fetchdatasource/fetchdatasource.go20
-rw-r--r--internal/frontend/server.go1
-rw-r--r--internal/postgres/package_symbol.go94
-rw-r--r--internal/testing/fakedatasource/fakedatasource.go28
7 files changed, 380 insertions, 77 deletions
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(), &params); 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)
+ }
+ }
+ })
+ }
+}
diff --git a/internal/datasource.go b/internal/datasource.go
index f6bf8c84..59f0afa1 100644
--- a/internal/datasource.go
+++ b/internal/datasource.go
@@ -95,6 +95,8 @@ type DataSource interface {
GetVersionsForPath(ctx context.Context, path string) ([]*ModuleInfo, error)
// GetModulePackages returns a list of packages in the given module version.
GetModulePackages(ctx context.Context, modulePath, version string) ([]*PackageMeta, error)
+ // GetSymbols returns symbols for the given unit and build context.
+ GetSymbols(ctx context.Context, pkgPath, modulePath, version string, bc BuildContext) ([]*Symbol, error)
// SearchSupport reports the search types supported by this datasource.
SearchSupport() SearchSupport
diff --git a/internal/fetchdatasource/fetchdatasource.go b/internal/fetchdatasource/fetchdatasource.go
index 1643d009..7a5f5669 100644
--- a/internal/fetchdatasource/fetchdatasource.go
+++ b/internal/fetchdatasource/fetchdatasource.go
@@ -433,3 +433,23 @@ func (ds *FetchDataSource) GetModulePackages(ctx context.Context, modulePath, ve
}
return metas, nil
}
+
+// GetSymbols returns symbols for the given unit and build context.
+func (ds *FetchDataSource) GetSymbols(ctx context.Context, pkgPath, modulePath, version string, bc internal.BuildContext) (_ []*internal.Symbol, err error) {
+ defer derrors.Wrap(&err, "FetchDataSource.GetSymbols(%q, %q, %q, %v)", pkgPath, modulePath, version, bc)
+
+ m, err := ds.getModule(ctx, modulePath, version)
+ if err != nil {
+ return nil, err
+ }
+ unit, err := ds.findUnit(ctx, m, pkgPath)
+ if err != nil {
+ return nil, err
+ }
+
+ doc := matchingDoc(unit.Documentation, bc)
+ if doc == nil || len(doc.API) == 0 {
+ return nil, derrors.NotFound
+ }
+ return doc.API, nil
+}
diff --git a/internal/frontend/server.go b/internal/frontend/server.go
index a1fd4516..6f4e5a9d 100644
--- a/internal/frontend/server.go
+++ b/internal/frontend/server.go
@@ -237,6 +237,7 @@ func (s *Server) Install(handle func(string, http.Handler), cacher Cacher, authV
handle("GET /files/", http.StripPrefix("/files", s.fileMux))
handle("GET /vuln/", vulnHandler)
handle("GET /v1/package/", s.errorHandler(api.ServePackage))
+ handle("GET /v1/symbols/", s.errorHandler(api.ServePackageSymbols))
handle("GET /v1/module/", s.errorHandler(api.ServeModule))
handle("GET /v1/versions/", s.errorHandler(api.ServeModuleVersions))
handle("GET /v1/packages/", s.errorHandler(api.ServeModulePackages))
diff --git a/internal/postgres/package_symbol.go b/internal/postgres/package_symbol.go
index aaa28267..4d99b07c 100644
--- a/internal/postgres/package_symbol.go
+++ b/internal/postgres/package_symbol.go
@@ -8,6 +8,7 @@ import (
"context"
"database/sql"
"fmt"
+ "sort"
"github.com/Masterminds/squirrel"
"golang.org/x/pkgsite/internal"
@@ -16,6 +17,93 @@ import (
"golang.org/x/pkgsite/internal/middleware/stats"
)
+// GetSymbols returns all of the symbols for a given package path and module path.
+func (db *DB) GetSymbols(ctx context.Context, pkgPath, modulePath, version string, bc internal.BuildContext) (_ []*internal.Symbol, err error) {
+ defer derrors.Wrap(&err, "DB.GetSymbols(ctx, %q, %q, %q, %v)", pkgPath, modulePath, version, bc)
+ defer stats.Elapsed(ctx, "DB.GetSymbols")()
+
+ query := packageSymbolQueryJoin(
+ squirrel.Select(
+ "s1.name AS symbol_name",
+ "s2.name AS parent_symbol_name",
+ "ps.section",
+ "ps.type",
+ "ps.synopsis",
+ "d.goos",
+ "d.goarch"), pkgPath, modulePath).
+ Where(squirrel.Eq{"m.version": version}).
+ OrderBy("CASE WHEN ps.type='Type' THEN 0 ELSE 1 END").
+ OrderBy("s1.name")
+
+ q, args, err := query.PlaceholderFormat(squirrel.Dollar).ToSql()
+ if err != nil {
+ return nil, err
+ }
+
+ resultsByBC := make(map[internal.BuildContext][]internal.SymbolMeta)
+ collect := func(rows *sql.Rows) error {
+ var (
+ name, parentName, synopsis, goos, goarch string
+ section internal.SymbolSection
+ kind internal.SymbolKind
+ )
+ if err := rows.Scan(&name, &parentName, &section, &kind, &synopsis, &goos, &goarch); err != nil {
+ return fmt.Errorf("row.Scan(): %v", err)
+ }
+ rowBC := internal.BuildContext{GOOS: goos, GOARCH: goarch}
+ if bc.Match(rowBC) {
+ resultsByBC[rowBC] = append(resultsByBC[rowBC], internal.SymbolMeta{
+ Name: name,
+ ParentName: parentName,
+ Section: section,
+ Kind: kind,
+ Synopsis: synopsis,
+ })
+ }
+ return nil
+ }
+
+ if err := db.db.RunQuery(ctx, q, collect, args...); err != nil {
+ return nil, err
+ }
+
+ if len(resultsByBC) == 0 {
+ return nil, derrors.NotFound
+ }
+
+ // Find the best build context among those that matched.
+ var matchedBCs []internal.BuildContext
+ for b := range resultsByBC {
+ matchedBCs = append(matchedBCs, b)
+ }
+ sort.Slice(matchedBCs, func(i, j int) bool {
+ return internal.CompareBuildContexts(matchedBCs[i], matchedBCs[j]) < 0
+ })
+ bestBC := matchedBCs[0]
+
+ var symbols []*internal.Symbol
+ symbolMap := make(map[string]*internal.Symbol)
+ rows := resultsByBC[bestBC]
+ for i := range rows {
+ sm := rows[i]
+ if sm.ParentName != "" && sm.ParentName != sm.Name {
+ if parent, ok := symbolMap[sm.ParentName]; ok {
+ parent.Children = append(parent.Children, &rows[i])
+ continue
+ }
+ }
+ // Treat as top-level if no parent or parent not found in this build context.
+ s := &internal.Symbol{
+ SymbolMeta: sm,
+ GOOS: bestBC.GOOS,
+ GOARCH: bestBC.GOARCH,
+ }
+ symbols = append(symbols, s)
+ symbolMap[sm.Name] = s
+ }
+ return symbols, nil
+}
+
// getPackageSymbols returns all of the symbols for a given package path and module path.
func getPackageSymbols(ctx context.Context, ddb *database.DB, packagePath, modulePath string,
) (_ *internal.SymbolHistory, err error) {
@@ -32,6 +120,8 @@ func getPackageSymbols(ctx context.Context, ddb *database.DB, packagePath, modul
"m.version",
"d.goos",
"d.goarch"), packagePath, modulePath).
+ Where("NOT m.incompatible").
+ Where(squirrel.Eq{"m.version_type": "release"}).
OrderBy("CASE WHEN ps.type='Type' THEN 0 ELSE 1 END").
OrderBy("s1.name")
q, args, err := query.PlaceholderFormat(squirrel.Dollar).ToSql()
@@ -64,9 +154,7 @@ func packageSymbolQueryJoin(query squirrel.SelectBuilder, pkgPath, modulePath st
Join("symbol_names s1 ON ps.symbol_name_id = s1.id").
Join("symbol_names s2 ON ps.parent_symbol_name_id = s2.id").
Where(squirrel.Eq{"p1.path": pkgPath}).
- Where(squirrel.Eq{"m.module_path": modulePath}).
- Where("NOT m.incompatible").
- Where(squirrel.Eq{"m.version_type": "release"})
+ Where(squirrel.Eq{"m.module_path": modulePath})
}
func collectSymbolHistory(check func(sh *internal.SymbolHistory, sm internal.SymbolMeta, v string, build internal.BuildContext) error) (*internal.SymbolHistory, func(rows *sql.Rows) error) {
diff --git a/internal/testing/fakedatasource/fakedatasource.go b/internal/testing/fakedatasource/fakedatasource.go
index 82212163..b44212a0 100644
--- a/internal/testing/fakedatasource/fakedatasource.go
+++ b/internal/testing/fakedatasource/fakedatasource.go
@@ -337,6 +337,34 @@ func (ds *FakeDataSource) GetModulePackages(ctx context.Context, modulePath, ver
return pkgs, nil
}
+// GetSymbols returns symbols for the given unit and build context.
+func (ds *FakeDataSource) GetSymbols(ctx context.Context, pkgPath, modulePath, version string, bc internal.BuildContext) ([]*internal.Symbol, error) {
+ m := ds.getModule(modulePath, version)
+ if m == nil {
+ return nil, derrors.NotFound
+ }
+ u := findUnit(m, pkgPath)
+ if u == nil {
+ return nil, derrors.NotFound
+ }
+
+ var bcs []internal.BuildContext
+ for b := range u.Symbols {
+ if bc.Match(b) {
+ bcs = append(bcs, b)
+ }
+ }
+ if len(bcs) == 0 {
+ return nil, derrors.NotFound
+ }
+
+ sort.Slice(bcs, func(i, j int) bool {
+ return internal.CompareBuildContexts(bcs[i], bcs[j]) < 0
+ })
+
+ return u.Symbols[bcs[0]], nil
+}
+
// SearchSupport reports the search types supported by this datasource.
func (ds *FakeDataSource) SearchSupport() internal.SearchSupport {
// internal/frontend.TestDetermineSearchAction depends on us returning FullSearch
generated by cgit v1.3 (git 2.53.0) at 2026-04-15 01:45:00 +0000