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 <ethanalee@google.com>
kokoro-CI: kokoro <noreply+kokoro@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

1 files changed, 114 insertions, 71 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 {