frontend

package
Version: v0.0.0-...-df8cc72 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 2, 2022 License: BSD-3-Clause Imports: 78 Imported by: 0

Documentation

Overview

Package frontend provides functionality for running the pkg.go.dev site.

Index

Constants

This section is empty.

Variables

View Source
var (

	// FetchLatencyDistribution aggregates frontend fetch request
	// latency by status code.
	FetchLatencyDistribution = &view.View{
		Name:    "go-discovery/frontend-fetch/latency",
		Measure: frontendFetchLatency,

		Aggregation: view.Distribution(
			1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100,
			130, 160, 200, 250, 300, 400, 500, 650, 800, 1000,
			30*60,
			60*60),
		Description: "FrontendFetch latency, by result source query type.",
		TagKeys:     []tag.Key{keyFetchStatus},
	}
	// FetchResponseCount counts frontend fetch responses by response type.
	FetchResponseCount = &view.View{
		Name:        "go-discovery/frontend-fetch/count",
		Measure:     frontendFetchLatency,
		Aggregation: view.Count(),
		Description: "Frontend fetch request count",
		TagKeys:     []tag.Key{keyFetchStatus},
	}
)
View Source
var (

	// DepsDevResultCount is a counter of results from fetching a URL from
	// deps.dev: either OK, canceled, timeout, or error.
	DepsDevResultCount = &view.View{
		Name:        "go-discovery/depsdev/result_count",
		Measure:     depsDevResults,
		Aggregation: view.Count(),
		Description: "deps.dev URL fetch results",
		TagKeys:     []tag.Key{keyDepsDevResult},
	}
)
View Source
var (
	VersionTypeCount = &view.View{
		Name:        "go-discovery/frontend_version_type/result_count",
		Measure:     versionTypeResults,
		Aggregation: view.Count(),
		Description: "version type results, by latest, master, or semver",
		TagKeys:     []tag.Key{keyVersionType},
	}
)

Functions

func FetchAndUpdateState

func FetchAndUpdateState(ctx context.Context, modulePath, requestedVersion string, proxyClient *proxy.Client, sourceClient *source.Client, db *postgres.DB) (_ int, err error)

FetchAndUpdateState is used by the InMemory queue for testing in internal/frontend and running cmd/frontend locally. It is a copy of worker.FetchAndUpdateState that does not update module_version_states, so that we don't have to import internal/worker here. It is not meant to be used when running on AppEngine.

func LegacyReadmeHTML

func LegacyReadmeHTML(_ context.Context, mi *internal.ModuleInfo, readme *internal.Readme) (_ safehtml.HTML, err error)

LegacyReadmeHTML sanitizes readmeContents based on bluemonday.UGCPolicy and returns a safehtml.HTML. If readmeFilePath indicates that this is a markdown file, it will also render the markdown contents using blackfriday.

This function is exported for use in an external tool that uses this package to compare readme files to see how changes in processing will affect them.

func ParseVersionsDetails

func ParseVersionsDetails(vd *VersionsDetails) (_ *internal.SymbolHistory, err error)

ParseVersionsDetails returns a map of versionToNameToUnitSymbol based on data from the provided VersionDetails.

func TagRoute

func TagRoute(route string, r *http.Request) string

TagRoute categorizes incoming requests to the frontend for use in monitoring.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

A Client for interacting with the frontend. This is only used for tests.

func NewClient

func NewClient(url string) *Client

NewClient creates a new frontend client. This is only used for tests.

func (*Client) GetVersions

func (c *Client) GetVersions(pkgPath string) (_ *VersionsDetails, err error)

GetVersions returns a VersionsDetails for the specified pkgPath. This is only used for tests.

func (*Client) Search

func (c *Client) Search(q, mode string) (_ *SearchPage, err error)

Search returns a SearchPage for a search query and mode.

type Directories

type Directories struct {
	// External contains all of the non-internal directories for the unit.
	External []*Directory

	// Internal contains the top level internal directory for the unit, if any.
	Internal *Directory
}

Directories is the directory listing for all directories in the unit, which is listed in the directories section of the main page.

type Directory

type Directory struct {
	// Prefix is the prefix of the unit path for the subdirectories.
	Prefix string

	// Root is the package located at prefix, nil for a directory.
	Root *DirectoryInfo

	// Subdirectories contains subdirectories with prefix trimmed from their suffix.
	Subdirectories []*DirectoryInfo
}

Directory is either a nested module or subdirectory of a unit, organized in a two level tree structure. This content is used in the directories section of the unit page.

type DirectoryInfo

type DirectoryInfo struct {
	Suffix   string
	URL      string
	Synopsis string
	IsModule bool
}

DirectoryInfo contains information about a package or nested module, relative to the path of a given unit. This content is used in the Directories section of the unit page.

type File

type File struct {
	Name string
	URL  string
}

File is a source file for a package.

type Heading

type Heading struct {
	// Level is the original level of the heading.
	Level int
	// Text is the content from the readme contained within a heading.
	Text string
	// ID corresponds to the ID attribute for a heading element
	// and is also used in an href to the corresponding section
	// within the readme outline. All ids are prefixed with readme-
	// to avoid name collisions.
	ID string
	// Children are nested headings.
	Children []*Heading
	// contains filtered or unexported fields
}

Heading holds data about a heading and nested headings within a readme. This data is used in the sidebar template to render the readme outline.

type ImportedByDetails

type ImportedByDetails struct {
	// ModulePath is the module path for the package referenced on this page.
	ModulePath string

	// ImportedBy is the collection of packages that import the
	// given package and are not part of the same module.
	// They are organized into a tree of sections by prefix.
	ImportedBy []*Section

	// NumImportedByDisplay is the display text at the top of the imported by
	// tab section, which shows the imported by count and package limit.
	NumImportedByDisplay string

	// Total is the total number of importers.
	Total int
}

ImportedByDetails contains information for the collection of packages that import a given package.

type ImportsDetails

type ImportsDetails struct {
	ModulePath string

	// ExternalImports is the collection of package imports that are not in
	// the Go standard library and are not part of the same module
	ExternalImports []string

	// InternalImports is an array of packages representing the package's
	// imports that are part of the same module.
	InternalImports []string

	// StdLib is an array of packages representing the package's imports
	// that are in the Go standard library.
	StdLib []string
}

ImportsDetails contains information for a package's imports.

type License

type License struct {
	*licenses.License
	Anchor safehtml.Identifier
	Source string
}

License contains information used for a single license section.

type LicenseMetadata

type LicenseMetadata struct {
	Type   string
	Anchor safehtml.Identifier
}

LicenseMetadata contains license metadata that is used in the package header.

type LicensesDetails

type LicensesDetails struct {
	Licenses []License
}

LicensesDetails contains license information for a package or module.

type MainDetails

type MainDetails struct {
	// Directories are packages and nested modules relative to the path for the
	// unit.
	Directories *Directories

	// Licenses contains license metadata used in the header.
	Licenses []LicenseMetadata

	// NumImports is the number of imports for the package.
	NumImports string

	// CommitTime is time that this version was published, or the time that
	// has elapsed since this version was committed if it was done so recently.
	CommitTime string

	// Readme is the rendered readme HTML.
	Readme safehtml.HTML

	// ReadmeOutline is a collection of headings from the readme file
	// used to render the readme outline in the sidebar.
	ReadmeOutline []*Heading

	// ReadmeLinks are from the "Links" section of this unit's readme file, and
	// are displayed on the right sidebar.
	ReadmeLinks []link

	// DocLinks are from the "Links" section of the Go package documentation,
	// and are displayed on the right sidebar.
	DocLinks []link

	// ModuleReadmeLinks are from the "Links" section of this unit's module, if
	// the unit is not itself a module. They are displayed on the right sidebar.
	// See https://golang.org/issue/42968.
	ModuleReadmeLinks []link

	// ImportedByCount is the number of packages that import this path.
	// When the count is > limit it will read as 'limit+'. This field
	// is not supported when using a datasource proxy.
	ImportedByCount string

	DocBody       safehtml.HTML
	DocOutline    safehtml.HTML
	MobileOutline safehtml.HTML
	IsPackage     bool

	// DocSynopsis is used as the content for the <meta name="Description">
	// tag on the main unit page.
	DocSynopsis string

	// GOOS and GOARCH are the build context for the doc.
	GOOS, GOARCH string

	// BuildContexts holds the values for build contexts available for the doc.
	BuildContexts []internal.BuildContext

	// SourceFiles contains .go files for the package.
	SourceFiles []*File

	// RepositoryURL is the URL to the repository containing the package.
	RepositoryURL string

	// SourceURL is the URL to the source of the package.
	SourceURL string

	// ExpandReadme is holds the expandable readme state.
	ExpandReadme bool

	// ModFileURL is an URL to the mod file.
	ModFileURL string

	// IsTaggedVersion is true if the version is not a psuedorelease.
	IsTaggedVersion bool

	// IsStableVersion is true if the major version is v1 or greater.
	IsStableVersion bool
}

MainDetails contains data needed to render the unit template.

type OSVEntry

type OSVEntry struct {
	*osv.Entry
}

OSVEntry holds an OSV entry and provides additional methods.

func (OSVEntry) AffectedModulesAndPackages

func (e OSVEntry) AffectedModulesAndPackages() []string

AffectedModulesAndPackages returns a list of names affected by a vuln.

type Readme

type Readme struct {
	HTML    safehtml.HTML // rendered HTML
	Outline []*Heading    // document headings
	Links   []link        // links from the "Links" section
}

Readme holds the result of processing a REAME file.

func ProcessReadme

func ProcessReadme(ctx context.Context, u *internal.Unit) (_ *Readme, err error)

ProcessReadme processes the README of unit u, if it has one. Processing includes rendering and sanitizing the HTML or Markdown, and extracting headings and links.

Headings are prefixed with "readme-" and heading levels are adjusted to start at h3 in order to nest them properly within the rest of the page. The readme's original styling is preserved in the html by giving headings a css class styled identical to their original heading level.

The extracted links are for display outside of the readme contents.

This function is exported for use by external tools.

type SearchPage

type SearchPage struct {

	// PackageTabQuery is the search query, stripped of any filters.
	// This is used if the user clicks on the package tab.
	PackageTabQuery string

	Pagination pagination
	Results    []*SearchResult
	// contains filtered or unexported fields
}

SearchPage contains all of the data that the search template needs to populate.

type SearchResult

type SearchResult struct {
	Name           string
	PackagePath    string
	ModulePath     string
	Version        string
	ChipText       string
	Synopsis       string
	DisplayVersion string
	Licenses       []string
	CommitTime     string
	NumImportedBy  string
	Symbols        *subResult
	SameModule     *subResult // package paths in the same module
	OtherMajor     *subResult // package paths in lower major versions
	SymbolName     string
	SymbolKind     string
	SymbolSynopsis string
	SymbolGOOS     string
	SymbolGOARCH   string
	SymbolLink     string
	Vulns          []vulns.Vuln
}

SearchResult contains data needed to display a single search result.

type Section

type Section struct {
	Prefix   string     // prefix for this section, or if Subs==nil, a single line
	Subs     []*Section // subsections
	NumLines int        // total number of lines in subsections
}

A Section represents a collection of lines with a common prefix. The collection is itself divided into sections by prefix, forming a tree.

func Sections

func Sections(lines []string, nextPrefix prefixFunc) []*Section

Sections transforms a list of lines, which must be sorted, into a list of Sections. Each Section in the result contains all the contiguous lines with the same prefix.

The nextPrefix function is responsible for extracting prefixes from lines.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server can be installed to serve the go discovery frontend.

func NewServer

func NewServer(scfg ServerConfig) (_ *Server, err error)

NewServer creates a new Server for the given database and template directory.

func (*Server) GetLatestInfo

func (s *Server) GetLatestInfo(ctx context.Context, unitPath, modulePath string, latestUnitMeta *internal.UnitMeta) internal.LatestInfo

GetLatestInfo returns various pieces of information about the latest versions of a unit and module:

  • The linkable form of the minor version of the unit.
  • The latest module path and the full unit path of any major version found given the fullPath and the modulePath.

It returns empty strings on error. It is intended to be used as an argument to middleware.LatestVersions.

func (*Server) Install

func (s *Server) Install(handle func(string, http.Handler), redisClient *redis.Client, authValues []string)

Install registers server routes using the given handler registration func. authValues is the set of values that can be set on authHeader to bypass the cache.

func (*Server) InstallFS

func (s *Server) InstallFS(path string, fsys fs.FS)

InstallFS adds path under the /files handler, serving the files in fsys.

func (*Server) PanicHandler

func (s *Server) PanicHandler() (_ http.HandlerFunc, err error)

PanicHandler returns an http.HandlerFunc that can be used in HTTP middleware. It returns an error if something goes wrong pre-rendering the error template.

type ServerConfig

type ServerConfig struct {
	Config *config.Config
	// DataSourceGetter should return a DataSource on each call.
	// It should be goroutine-safe.
	DataSourceGetter     func(context.Context) internal.DataSource
	Queue                queue.Queue
	TaskIDChangeInterval time.Duration
	TemplateFS           template.TrustedFS // for loading templates safely
	StaticFS             fs.FS              // for static/ directory
	ThirdPartyFS         fs.FS              // for third_party/ directory
	DevMode              bool
	StaticPath           string // used only for dynamic loading in dev mode
	ReportingClient      *errorreporting.Client
	VulndbClient         vulnc.Client
}

ServerConfig contains everything needed by a Server.

type StyleSection

type StyleSection struct {
	// ID is the ID for the header element of the section.
	ID string

	// Title is the title of the section, taken from the name
	// of the markdown file.
	Title string

	// Content is the HTML rendered from the parsed markdown file.
	Content safehtml.HTML

	// Outline is a collection of headings used in the navigation.
	Outline []*Heading
}

StyleSection represents a section on the styleguide page.

type Symbol

type Symbol struct {
	// Name is name of the symbol. At a given package version, name must be
	// unique.
	Name string

	// Synopsis is the one line description of the symbol that is displayed.
	Synopsis string

	// Section is the section that a symbol appears in.
	Section internal.SymbolSection

	// Kind is the type of a symbol, which is either a constant, variable,
	// function, type, field or method.
	Kind internal.SymbolKind

	// Link is the link to the symbol name on pkg.go.dev.
	Link string

	// Children contain the child symbols for this symbol. This will
	// only be populated when the SymbolType is "Type". For example, the
	// children of net/http.Handler are FileServer, NotFoundHandler,
	// RedirectHandler, StripPrefix, and TimeoutHandler. Each child
	// symbol will have ParentName set to the Name of this type.
	Children []*Symbol

	// Builds lists all of the build contexts supported by the symbol, it is
	// only available for limited set of builds. If the symbol supports all
	// build contexts, Builds will be nil.
	Builds []string

	// New indicates that the symbol is new as of the version where it is
	// present. For example, if type Client was introduced in v1.0.0 and
	// Client.Timeout was introduced in v1.1.0, New will be false for Client
	// and true for Client.Timeout if this Symbol corresponds to v1.1.0.
	New bool
	// contains filtered or unexported fields
}

Symbol is an element in the package API. A symbol can be a constant, variable, function, type, field or method.

type TabSettings

type TabSettings struct {
	// Name is the tab name used in the URL.
	Name string

	// DisplayName is the formatted tab name.
	DisplayName string

	// AlwaysShowDetails defines whether the tab content can be shown even if the
	// package is not determined to be redistributable.
	AlwaysShowDetails bool

	// TemplateName is the name of the template used to render the
	// corresponding tab, as defined in Server.templates.
	TemplateName string

	// Disabled indicates whether a tab should be displayed as disabled.
	Disabled bool
}

TabSettings defines tab-specific metadata.

type UnitPage

type UnitPage struct {

	// Unit is the unit for this page.
	Unit *internal.UnitMeta

	// Breadcrumb contains data used to render breadcrumb UI elements.
	Breadcrumb breadcrumb

	// Title is the title of the page.
	Title string

	// URLPath is the path suitable for links on the page.
	// See the unitURLPath for details.
	URLPath string

	// CanonicalURLPath is a permanent representation of the URL path for a
	// unit.
	// It uses the resolved module path and version.
	// For example, if the latest version of /my.module/pkg is version v1.5.2,
	// the canonical URL path for that unit would be /my.module@v1.5.2/pkg
	CanonicalURLPath string

	// The version string formatted for display.
	DisplayVersion string

	// LinkVersion is version string suitable for links used to compute
	// latest badges.
	LinkVersion string

	// LatestURL is a url pointing to the latest version of a unit.
	LatestURL string

	// IsLatestMinor is true if the version displayed is the latest minor of the unit.
	// Used to determine the canonical URL for search engines and robots meta directives.
	IsLatestMinor bool

	// LatestMinorClass is the CSS class that describes the current unit's minor
	// version in relationship to the latest version of the unit.
	LatestMinorClass string

	// Information about the latest major version of the module.
	LatestMajorVersion    string
	LatestMajorVersionURL string

	// PageType is the type of page (pkg, cmd, dir, std, or mod).
	PageType string

	// PageLabels are the labels that will be displayed
	// for a given page.
	PageLabels []string

	// CanShowDetails indicates whether details can be shown or must be
	// hidden due to issues like license restrictions.
	CanShowDetails bool

	// Settings contains settings for the selected tab.
	SelectedTab TabSettings

	// RedirectedFromPath is the path that redirected to the current page.
	// If non-empty, a "redirected from" banner will be displayed
	// (see static/frontend/unit/_header.tmpl).
	RedirectedFromPath string

	// Details contains data specific to the type of page being rendered.
	Details any

	// Vulns holds vulnerability information.
	Vulns []vulns.Vuln

	// DepsDevURL holds the full URL to this module version on deps.dev.
	DepsDevURL string

	// IsGoProject is true if the package is from the standard library or a
	// golang.org sub-repository.
	IsGoProject bool
	// contains filtered or unexported fields
}

UnitPage contains data needed to render the unit template.

type VersionList

type VersionList struct {
	VersionListKey
	// Deprecated indicates whether the major version is deprecated.
	Deprecated bool
	// DeprecationComment holds the reason for deprecation, if any.
	DeprecationComment string
	// Versions holds the nested version summaries, organized in descending
	// semver order.
	Versions []*VersionSummary
}

VersionList holds all versions corresponding to a unique (module path, major version) tuple in the version hierarchy.

type VersionListKey

type VersionListKey struct {
	// ModulePath is the module path of this major version.
	ModulePath string

	// Major is the major version string (e.g. v1, v2)
	Major string

	// Incompatible indicates whether the VersionListKey represents an
	// incompatible module version.
	Incompatible bool
}

VersionListKey identifies a version list on the versions tab. We have a separate VersionList for each major version of a module series. Notably we have more version lists than module paths: v0 and v1 module versions are in separate version lists, despite having the same module path. Also note that major version isn't sufficient as a key: there are packages contained in the same major version of different modules, for example github.com/hashicorp/vault/api, which exists in v1 of both of github.com/hashicorp/vault and github.com/hashicorp/vault/api.

type VersionSummary

type VersionSummary struct {
	CommitTime string
	// Link to this version, for use in the anchor href.
	Link                string
	Version             string
	Retracted           bool
	RetractionRationale string
	IsMinor             bool
	Symbols             [][]*Symbol
	Vulns               []vulns.Vuln
}

VersionSummary holds data required to format the version link on the versions tab.

type VersionsDetails

type VersionsDetails struct {
	// ThisModule is the slice of VersionLists with the same module path as the
	// current package.
	ThisModule []*VersionList

	// IncompatibleModules is the slice of the VersionsLists with the same
	// module path as the current package, but with incompatible versions.
	IncompatibleModules []*VersionList

	// OtherModules is the slice of VersionLists with a different module path
	// from the current package.
	OtherModules []string
}

VersionsDetails contains the hierarchy of version summary information used to populate the version tab. Version information is organized into separate lists, one for each (ModulePath, Major Version) pair.

type VulnListPage

type VulnListPage struct {
	Entries []OSVEntry
	// contains filtered or unexported fields
}

VulnListPage holds the information for a page that lists vuln entries.

type VulnPage

type VulnPage struct {
	Entry            OSVEntry
	AffectedPackages []*vulns.AffectedPackage
	AliasLinks       []link
	AdvisoryLinks    []link
	// contains filtered or unexported fields
}

VulnPage holds the information for a page that displays a single vuln entry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL