Package-Level Type Names (total 47, in which 25 are exported)
/* sort exporteds by: | */
Directories is the directory listing for all directories in the unit,
which is listed in the directories section of the main page.
External contains all of the non-internal directories for the unit.
Internal contains the top level internal directory for the unit, if any.
func unitDirectories(directories []*DirectoryInfo) *Directories
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.
Prefix is the prefix of the unit path for the subdirectories.
Root is the package located at prefix, nil for a directory.
Subdirectories contains subdirectories with prefix trimmed from their suffix.
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.
Children are nested headings.
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.
Level is the original level of the heading.
Text is the content from the readme contained within a heading.
parent is the heading this heading is nested within. Nil for top
level headings.
ImportedByDetails contains information for the collection of packages that
import a given package.
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.
ModulePath is the module path for the package referenced on this page.
NumImportedByDisplay is the display text at the top of the imported by
tab section, which shows the imported by count and package limit.
Total is the total number of importers.
func fetchImportedByDetails(ctx context.Context, ds internal.DataSource, pkgPath, modulePath string) (*ImportedByDetails, error)
ImportsDetails contains information for a package's imports.
ExternalImports is the collection of package imports that are not in
the Go standard library and are not part of the same module
InternalImports is an array of packages representing the package's
imports that are part of the same module.
ModulePathstring
StdLib is an array of packages representing the package's imports
that are in the Go standard library.
func fetchImportsDetails(ctx context.Context, ds internal.DataSource, pkgPath, modulePath, resolvedVersion string) (_ *ImportsDetails, err error)
MainDetails contains data needed to render the unit template.
BuildContexts holds the values for build contexts available for the doc.
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.
Directories are packages and nested modules relative to the path for the
unit.
DocBodysafehtml.HTML
DocLinks are from the "Links" section of the Go package documentation,
and are displayed on the right sidebar.
DocOutlinesafehtml.HTML
DocSynopsis is used as the content for the <meta name="Description">
tag on the main unit page.
ExpandReadme is holds the expandable readme state.
GOOS and GOARCH are the build context for the doc.
GOOS and GOARCH are the build context for the doc.
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.
IsPackagebool
IsStableVersion is true if the major version is v1 or greater.
IsTaggedVersion is true if the version is not a psuedorelease.
Licenses contains license metadata used in the header.
MobileOutlinesafehtml.HTML
ModFileURL is an URL to the mod file.
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.
NumImports is the number of imports for the package.
Readme is the rendered readme HTML.
ReadmeLinks are from the "Links" section of this unit's readme file, and
are displayed on the right sidebar.
ReadmeOutline is a collection of headings from the readme file
used to render the readme outline in the sidebar.
RepositoryURL is the URL to the repository containing the package.
SourceFiles contains .go files for the package.
SourceURL is the URL to the source of the package.
func fetchMainDetails(ctx context.Context, ds internal.DataSource, um *internal.UnitMeta, expandReadme bool, bc internal.BuildContext) (_ *MainDetails, err error)
SearchPage contains all of the data that the search template needs to
populate.
AllowWideContent indicates whether the content should be displayed in a
way that’s amenable to wider viewports.
AppVersionLabel contains the current version of the app.
DevMode indicates whether the server is running in development mode.
Experiments contains the experiments currently active.
GoogleTagManagerID is the ID used to load Google Tag Manager.
HTMLTitle is the value to use in the page’s <title> tag.
MetaDescription is the html used for rendering the <meta name="Description"> tag.
Query is the current search query (if applicable).
PaginationpaginationResults[]*SearchResultbasePagebasePage
func fetchSearchPage(ctx context.Context, db *postgres.DB, query string, pageParams paginationParams) (*SearchPage, error)
A Section represents a collection of lines with a common prefix. The
collection is itself divided into sections by prefix, forming a tree.
// total number of lines in subsections
// prefix for this section, or if Subs==nil, a single line
// subsections
(*T) add(sub *Section)
func Sections(lines []string, nextPrefix prefixFunc) []*Section
func newSection(prefix string) *Section
func section(prefix string, lines []string, nextPrefix prefixFunc) (*Section, []string)
func (*Section).add(sub *Section)
Server can be installed to serve the go discovery frontend.
appVersionLabelstring
cmplClient is a redis client that has access to the "completions" sorted
set.
devModeboolerrorPage[]byte
getDataSource should never be called from a handler. It is called only in Server.errorHandler.
googleTagManagerIDstring
// Protects all fields below
queuequeue.QueuereportingClient*errorreporting.ClientserveStatsboolstaticPathtemplate.TrustedSourcetaskIDChangeIntervaltime.DurationtemplateDirtemplate.TrustedSourcetemplatesmap[string]*template.TemplatethirdPartyPathstring
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.
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.
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.
badgeHandler serves a Go SVG badge image for requests to /badge/<path>
and a badge generation tool page for requests to /badge/[?path=<path>].
checkPossibleModulePaths checks all modulePaths at the requestedVersion, to see
if the fullPath exists. For each module path, it first checks version_map to
see if we already attempted to fetch the module. If not, and shouldQueue is
true, it will enqueue the module to the frontend task queue to be fetched.
checkPossibleModulePaths will then poll the database for each module path,
until a result is returned or the request times out. If shouldQueue is false,
it will return the fetchResult, regardless of what the status is.
(*T) errorHandler(f func(w http.ResponseWriter, r *http.Request, ds internal.DataSource) error) http.HandlerFunc(*T) fetchAndPoll(ctx context.Context, ds internal.DataSource, modulePath, fullPath, requestedVersion string) (status int, responseText string)(*T) findTemplate(templateName string) (*template.Template, error)
fmtHandler takes a Go program in its "body" form value, formats it with
standard gofmt formatting, and writes a fmtResponse as a JSON object.
handleModuleDetailsRedirect redirects all redirects to "/mod" to "/".
handlePackageDetailsRedirect redirects all redirects to "/pkg" to "/".
(*T) licensePolicyHandler() http.HandlerFunc
newBasePage returns a base page for the given request and title.
proxyPlayground is a handler that proxies playground requests to play.golang.org.
renderErrorPage executes error.tmpl with the given errorPage
renderPage executes the given templateName with page.
reportError sends the error to the GCP Error Reporting service.
serveDetails handles requests for package/directory/module details pages. It
expects paths of the form "/<module-path>[@<version>?tab=<tab>]".
stdlib module pages are handled at "/std", and requests to "/mod/std" will
be redirected to that path.
(*T) serveError(w http.ResponseWriter, r *http.Request, err error)(*T) serveErrorPage(w http.ResponseWriter, r *http.Request, status int, page *errorPage)
serveFetch checks if a requested path and version exists in the database.
If not, it will enqueuing potential module versions that could contain
the requested path and version to a task queue, to be fetched by the worker.
Meanwhile, the request will poll the database until a row is found, or a
timeout occurs. A status and responseText will be returned based on the
result of the request.
servePage is used to execute all templates for a *Server.
servePathNotFoundPage serves a 404 page for the requested path, or redirects
the user to an appropriate location.
serveSearch applies database data to the search template. Handles endpoint
/search?q=<query>. If <query> is an exact match for a package path, the user
will be redirected to the details page.
serveStyleGuide serves the styleguide page, the content of which is
generated from the markdown files in content/static.
serveUnitPage serves a unit page for a path using the paths,
modules, documentation, readmes, licenses, and package_imports tables.
(*T) staticHandler() http.Handler
staticPageHandler handles requests to a template that contains no dynamic
content.
func NewServer(scfg ServerConfig) (_ *Server, err error)
StyleSection represents a section on the styleguide page.
Content is the HTML rendered from the parsed markdown file.
ID is the ID for the header element of the section.
Outline is a collection of headings used in the navigation.
Title is the title of the section, taken from the name
of the markdown file.
func styleSection(ctx context.Context, filename string) (_ *StyleSection, err error)
Symbol is an element in the package API. A symbol can be a constant,
variable, function, type, field or method.
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.
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.
Kind is the type of a symbol, which is either a constant, variable,
function, type, field or method.
Link is the link to the symbol name on pkg.go.dev.
Name is name of the symbol. At a given package version, name must be
unique.
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.
Section is the section that a symbol appears in.
Synopsis is the one line description of the symbol that is displayed.
builds keeps track of build contexts used to generate Builds.
(*T) addBuilds(builds ...internal.BuildContext)
func createParent(parentName, pkgURLPath string, builds ...internal.BuildContext) *Symbol
func findParent(parentName string, cus *internal.SymbolBuildContexts, nameToMetaToSymbol map[string]map[internal.SymbolMeta]*Symbol) *Symbol
func sortSymbols(symbols []*Symbol) [][]*Symbol
func symbolsForVersion(pkgURLPath string, symbolsAtVersion map[string]map[internal.SymbolMeta]*internal.SymbolBuildContexts) [][]*Symbol
func addSymbol(s *Symbol, v string, sh *internal.SymbolHistory, builds []string)
func findParent(parentName string, cus *internal.SymbolBuildContexts, nameToMetaToSymbol map[string]map[internal.SymbolMeta]*Symbol) *Symbol
func sortSymbols(symbols []*Symbol) [][]*Symbol
func sortSymbolsGroup(syms []*Symbol)
TabSettings defines tab-specific metadata.
AlwaysShowDetails defines whether the tab content can be shown even if the
package is not determined to be redistributable.
Disabled indicates whether a tab should be displayed as disabled.
DisplayName is the formatted tab name.
Name is the tab name used in the URL.
TemplateName is the name of the template used to render the
corresponding tab, as defined in Server.templates.
UnitPage contains data needed to render the unit template.
AllowWideContent indicates whether the content should be displayed in a
way that’s amenable to wider viewports.
AppVersionLabel contains the current version of the app.
DevMode indicates whether the server is running in development mode.
Experiments contains the experiments currently active.
GoogleTagManagerID is the ID used to load Google Tag Manager.
HTMLTitle is the value to use in the page’s <title> tag.
MetaDescription is the html used for rendering the <meta name="Description"> tag.
Query is the current search query (if applicable).
Breadcrumb contains data used to render breadcrumb UI elements.
CanShowDetails indicates whether details can be shown or must be
hidden due to issues like license restrictions.
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
Details contains data specific to the type of page being rendered.
The version string formatted for display.
Information about the latest major version of the module.
LatestMajorVersionURLstring
LatestMinorClass is the CSS class that describes the current unit's minor
version in relationship to the latest version of the unit.
LatestURL is a url pointing to the latest version of a unit.
LinkVersion is version string suitable for links used to compute
latest badges.
PageLabels are the labels that will be displayed
for a given page.
PageType is the type of page (pkg, cmd, dir, std, or mod).
RedirectedFromPath is the path that redirected to the current page.
If non-empty, a "redirected from" banner will be displayed
(see content/static/html/helpers/_unit_header.tmpl).
Settings contains settings for the selected tab.
Title is the title of the page.
URLPath is the path suitable for links on the page.
See the unitURLPath for details.
Unit is the unit for this page.
basePagebasePage
VersionList holds all versions corresponding to a unique (module path,
major version) tuple in the version hierarchy.
VersionListKeyVersionListKey
Deprecated indicates whether the major version is deprecated.
DeprecationComment holds the reason for deprecation, if any.
Incompatible indicates whether the VersionListKey represents an
incompatible module version.
Major is the major version string (e.g. v1, v2)
ModulePath is the module path of this major version.
Versions holds the nested version summaries, organized in descending
semver order.
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.
Deprecated indicates whether the major version is deprecated.
DeprecationComment holds the reason for deprecation, if any.
Incompatible indicates whether the VersionListKey represents an
incompatible module version.
Major is the major version string (e.g. v1, v2)
ModulePath is the module path of this major version.
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.
IncompatibleModules is the slice of the VersionsLists with the same
module path as the current package, but with incompatible versions.
OtherModules is the slice of VersionLists with a different module path
from the current package.
ThisModule is the slice of VersionLists with the same module path as the
current package.
func buildVersionDetails(currentModulePath string, modInfos []*internal.ModuleInfo, sh *internal.SymbolHistory, linkify func(v *internal.ModuleInfo) string) *VersionsDetails
func fetchVersionsDetails(ctx context.Context, ds internal.DataSource, fullPath, modulePath string) (*VersionsDetails, error)
func ParseVersionsDetails(vd VersionsDetails) (_ *internal.SymbolHistory, err error)
astTransformer is a default transformer of the goldmark tree. We pass in
readme information to use for the link transformations.
info*source.Inforeadme*internal.Readme
Transform transforms the given AST tree.
*T : github.com/yuin/goldmark/parser.ASTTransformer
BadgePath is the URL path of the badge SVG.
AllowWideContent indicates whether the content should be displayed in a
way that’s amenable to wider viewports.
AppVersionLabel contains the current version of the app.
DevMode indicates whether the server is running in development mode.
Experiments contains the experiments currently active.
GoogleTagManagerID is the ID used to load Google Tag Manager.
HTMLTitle is the value to use in the page’s <title> tag.
MetaDescription is the html used for rendering the <meta name="Description"> tag.
Query is the current search query (if applicable).
LinkPath is the URL path of the badge will link to.
basePagebasePage
basePage contains fields shared by all pages when rendering templates.
AllowWideContent indicates whether the content should be displayed in a
way that’s amenable to wider viewports.
AppVersionLabel contains the current version of the app.
DevMode indicates whether the server is running in development mode.
Experiments contains the experiments currently active.
GoogleTagManagerID is the ID used to load Google Tag Manager.
HTMLTitle is the value to use in the page’s <title> tag.
MetaDescription is the html used for rendering the <meta name="Description"> tag.
Query is the current search query (if applicable).
func (*Server).newBasePage(r *http.Request, title string) basePage
errorPage contains fields for rendering a HTTP error page.
AllowWideContent indicates whether the content should be displayed in a
way that’s amenable to wider viewports.
AppVersionLabel contains the current version of the app.
DevMode indicates whether the server is running in development mode.
Experiments contains the experiments currently active.
GoogleTagManagerID is the ID used to load Google Tag Manager.
HTMLTitle is the value to use in the page’s <title> tag.
MetaDescription is the html used for rendering the <meta name="Description"> tag.
Query is the current search query (if applicable).
MessageDatainterface{}basePagebasePagemessageTemplatetemplate.TrustedTemplatetemplateNamestring
func (*Server).renderErrorPage(ctx context.Context, status int, templateName string, page *errorPage) ([]byte, error)
func (*Server).serveErrorPage(w http.ResponseWriter, r *http.Request, status int, page *errorPage)
Headings[]*Headingctxcontext.Context
// omit title from TOC
Transform collects the headings from a readme into an outline
of the document. It nests the headings based on the h-level hierarchy.
See tests for heading levels in TestReadme for behavior.
*T : github.com/yuin/goldmark/parser.ASTTransformer
ids is a collection of element ids in document.
valuesmap[string]bool
Generate turns heading content from a markdown document into a heading id.
First HTML markup and markdown images are stripped then unicode letters
and numbers are used to generate the final result. Finally, all heading ids
are prefixed with "readme-" to avoid name collisions with other ids on the
unit page. Duplicated heading ids are given an incremental suffix. See
readme_test.go for examples.
Put implements Put from the goldmark parser IDs interface.
*T : github.com/yuin/goldmark/parser.IDs
licensePolicyPage is used to generate the static license policy page.
AllowWideContent indicates whether the content should be displayed in a
way that’s amenable to wider viewports.
AppVersionLabel contains the current version of the app.
DevMode indicates whether the server is running in development mode.
Experiments contains the experiments currently active.
GoogleTagManagerID is the ID used to load Google Tag Manager.
HTMLTitle is the value to use in the page’s <title> tag.
MetaDescription is the html used for rendering the <meta name="Description"> tag.
Query is the current search query (if applicable).
LicenseFileNames[]stringLicenseTypes[]licenses.AcceptedLicenseInfobasePagebasePage
pagination holds information related to paginated display. It is intended to
be part of a view model struct.
Given a sequence of results with offsets 0, 1, 2 ... (typically from a
database query), we paginate it by dividing it into numbered pages
1, 2, 3, .... Each page except possibly the last has the same number of results.
// whether or not the total count is approximate
// " " " next page, usually Page+1, but zero on the last page
// offset of the first item on the current page
// number of the current page
// consecutive page numbers to be displayed for navigation
// " " " previous page, usually Page-1 but zero if Page == 1
// number of results on this page
// total number of results
// URL common to all pages
// the maximum number of results on a page
PageURL constructs a URL that displays the given page.
It adds a "page" query parameter to the base URL.
func newPagination(params paginationParams, resultCount, totalCount int) pagination
A prefixFunc returns the next prefix of s, given the current prefix.
It should return the empty string if there are no more prefixes.
func Sections(lines []string, nextPrefix prefixFunc) []*Section
func section(prefix string, lines []string, nextPrefix prefixFunc) (*Section, []string)
AllowWideContent indicates whether the content should be displayed in a
way that’s amenable to wider viewports.
AppVersionLabel contains the current version of the app.
DevMode indicates whether the server is running in development mode.
Experiments contains the experiments currently active.
GoogleTagManagerID is the ID used to load Google Tag Manager.
HTMLTitle is the value to use in the page’s <title> tag.
MetaDescription is the html used for rendering the <meta name="Description"> tag.
Query is the current search query (if applicable).
Outline[]*HeadingSections[]*StyleSectionbasePagebasePage
func styleGuide(ctx context.Context, staticPath string) (_ *styleGuidePage, err error)
fullPath is the full import path corresponding to the requested
package/module/directory page.
modulePath is the path of the module corresponding to the fullPath and
resolvedVersion. If unknown, it is set to internal.UnknownModulePath.
requestedVersion is the version requested by the user, which will be one
of the following: "latest", "master", a Go version tag, or a semantic
version.
func extractURLPathInfo(urlPath string) (_ *urlPathInfo, err error)
func parseDetailsURLPath(urlPath string) (_ *urlPathInfo, err error)
func parseStdLibURLPath(urlPath string) (_ *urlPathInfo, err error)
func (*Server).serveUnitPage(ctx context.Context, w http.ResponseWriter, r *http.Request, ds internal.DataSource, info *urlPathInfo) (err error)
Package-Level Functions (total 121, in which 7 are exported)
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.
LegacyReadmeHTML sanitizes readmeContents based on bluemondy.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.
NewServer creates a new Server for the given database and template directory.
ParseVersionsDetails returns a map of versionToNameToUnitSymbol based on
data from the proovided VersionDetails.
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.
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.
TagRoute categorizes incoming requests to the frontend for use in
monitoring.
absoluteTime takes a date and returns returns a human-readable,
date with the format mmm d, yyyy:
accountPrefix guesses the prefix of the path (split into parts at "/")
that corresponds to the account.
approximateNumber returns an approximation of the estimate, calibrated by
the statistical estimate of standard error.
i.e., a number that isn't misleading when we say '1-10 of approximately N
results', but that is still close to our estimate.
breadcrumbPath builds HTML that displays pkgPath as a sequence of links
to its parents.
pkgPath is a slash-separated path, and may be a package import path or a directory.
modPath is the package's module path. This will be a prefix of pkgPath, except
within the standard library.
version is the version for the module, or LatestVersion.
See TestBreadcrumbPath for examples.
buildVersionDetails constructs the version hierarchy to be rendered on the
versions tab, organizing major versions into those that have the same module
path as the package version under consideration, and those that don't. The
given versions MUST be sorted first by module path and then by semver.
camelCase turns a snake cased strink into a camel case string.
For example, hello-world becomes HelloWorld. This function is
used to ensure proper casing in the classnames of the style
sections.
candidateModulePaths returns the potential module paths that could contain
the fullPath. The paths are returned in reverse length order.
canonicalURLPath constructs a URL path to the unit that always includes the
resolved version.
checkForPath checks for the existence of fullPath, modulePath, and
requestedVersion in the database. If the modulePath does not exist in
version_map, it returns errModuleNotInVersionMap, signaling that the fetch
process that was initiated is not yet complete. If the row exists version_map
but not paths, it means that a module was found at the requestedVersion, but
not the fullPath, so errPathDoesNotExistInModule is returned.
Note that if an error occurs while writing to the version_map table,
checkForPath will not know. Instead, it will keep running until the request
times out.
constructUnitURL returns a URL path that refers to the given unit at the requested
version. If requestedVersion is "latest", then the resulting path has no
version; otherwise, it has requestedVersion.
createParent creates a parent symbol for the provided unit symbol. This is
used when us is a child of a symbol that may have been introduced at a
different version. The symbol created will have New set to false, since this
function is only used when a parent symbol is not found for the unit symbol,
which means it was not introduced at the same version.
detailsTTL assigns the cache TTL for package detail requests.
displayVersion returns the version string, formatted for display.
effectiveName returns either the command name or package name.
elapsedTime takes a date and returns returns human-readable,
relative timestamps based on the following rules:
(1) 'X hours ago' when X < 6
(2) 'today' between 6 hours and 1 day ago
(3) 'Y days ago' when Y < 6
(4) A date formatted like "Jan 2, 2006" for anything further back
extractURLPathInfo extracts information from a request to pkg.go.dev.
If an error is returned, the user will be served an http.StatusBadRequest.
fetchDetailsForPackage returns tab details by delegating to the correct detail
handler.
fetchImportedByDetails fetches importers for the package version specified by
path and version from the database and returns a ImportedByDetails.
fetchImportsDetails fetches imports for the package version specified by
pkgPath, modulePath and version from the database and returns a ImportsDetails.
fetchLicensesDetails fetches license data for the package version specified by
path and version from the database and returns a LicensesDetails.
fileSource returns the original filepath in the module zip where the given
filePath can be found. For std, the corresponding URL in
go.google.source.com/go is returned.
formatVersion formats a more readable representation of the given version
string. On any parsing error, it simply returns the input unmodified.
For pseudo versions, the version string will use a shorten commit hash of 7
characters to identify the version, and hide timestamp using ellipses.
For any version string longer than 25 characters, the pre-release string will be
truncated, such that the string displayed is exactly 25 characters, including the ellipses.
See TestFormatVersion for examples.
goTagForVersion returns the Go tag corresponding to a given semantic
version. It should only be used if we are 100% sure the version will
correspond to a Go tag, such as when we are fetching the version from the
database.
legacySanitizeHTML reads HTML from r and sanitizes it to ensure it is safe.
licenseAnchors returns anchors (HTML identifiers) for all the paths, in the
same order. If the paths are unique, it ensures that the resulting anchors
are unique. The argument is modified.
linkVersion returns the version string, suitable for use in
a link to this site.
TODO(golang/go#41855): Clarify definition / use case for linkVersion and
other version strings.
makePlaygroundProxy creates a proxy that sends requests to play.golang.org.
The prefix /play is removed from the URL path.
markdownFiles walks the content/static directory and collects
the paths to markdown files.
metaDescription uses a safehtml escape hatch to build HTML used
to render the <meta name="Description"> for unit pages as a
workaround for https://github.com/google/safehtml/issues/6.
modulePathsToFetch returns the slice of module paths that we should check
for the path. If modulePath is known, only check that modulePath. If a row
for the fullPath already exists, check that modulePath. Otherwise, check all
possible module paths based on the elements for the fullPath.
Resulting paths are returned in reverse length order.
newContextFromExps adds and removes experiments from the context's experiment
set, creates a new set with the changes, and returns a context with the new
set. Each string in expMods can be either an experiment name, which means
that the experiment should be added, or "!" followed by an experiment name,
meaning that it should be removed.
newHTMLRenderer creates a new HTMLRenderer for a readme.
newIDs creates a collection of element ids in a document.
newPagination constructs a pagination. Call it after some results have been
obtained.
resultCount is the number of results in the current page.
totalCount is the total number of results.
newPaginationParams extracts pagination params from the request.
next returns the number of the page after the given page, or zero if page is is the last page or larger.
limit and totalCount are used to calculate the last page (see numPages).
nextPrefixAccount is a prefixFunc (see above). Its first argument
is an import path, and its second is the previous prefix that it returned
for that path, or "" if this is the first prefix.
nextPrefixAccount tries to return an initial prefix for path
that consists of the "account": the entity controlling the
remainder of the path. In the most common case, paths beginning
with "github.com", the account is the second path element, the GitHub user or org.
So for example, the first prefix of "github.com/google/go-cmp/cmp" is
"github.com/google/".
nextPrefixAccount returns a second prefix that is one path element past the
account. For github.com paths, this is the repo. Continuing the above example,
the second prefix is "github.com/google/go-cmp/".
nextPrefixAccount does not return any prefixes beyond those two.
numPages is the total number of pages needed to display all the results,
given the specified maximum page size and the total number of results.
offset returns the offset of the first result on page, assuming all previous
pages were of size limit.
pageLabels determines the labels to display for a given unit.
See TestPageTitlesAndTypes for examples.
pagesToLink returns the page numbers that will be displayed. Given a
page, it returns a slice containing numPagesToLink integers in ascending
order and optimizes for page to be in the middle of that range. The max
value of an integer in the return slice will be less than numPages.
pageTitle determines the pageTitles for a given unit.
See TestPageTitlesAndTypes for examples.
pageType determines the pageType for a given unit.
parseDetailsURLPath parses a URL path that refers (or may refer) to something
in the Go ecosystem.
After trimming leading and trailing slashes, the path is expected to have one
of three forms, and we divide it into three parts: a full path, a module
path, and a version.
1. The path has no '@', like github.com/hashicorp/vault/api.
This is the full path. The module path is unknown. So is the version, so we
treat it as the latest version for whatever the path denotes.
2. The path has "@version" at the end, like github.com/hashicorp/vault/api@v1.2.3.
We split this at the '@' into a full path (github.com/hashicorp/vault/api)
and version (v1.2.3); the module path is still unknown.
3. The path has "@version" in the middle, like github.com/hashicorp/vault@v1.2.3/api.
(We call this the "canonical" form of a path.)
We remove the version to get the full path, which is again
github.com/hashicorp/vault/api. The version is v1.2.3, and the module path is
the part before the '@', github.com/hashicorp/vault.
In one case, we do a little more than parse the urlPath into parts: if the full path
could be a part of the standard library (because it has no '.'), we assume it
is and set the modulePath to indicate the standard library.
parsePageTemplates parses html templates contained in the given base
directory in order to generate a map of Name->*template.Template.
Separate templates are used so that certain contextual functions (e.g.
templateName) can be bound independently for each page.
pathInVersion constructs the full import path of the package corresponding
to mi, given its v1 path. To do this, we first compute the suffix of the
package path in the given module series, and then append it to the real
(versioned) module path.
For example: if we're considering package foo.com/v3/bar/baz, and encounter
module version foo.com/bar/v2, we do the following:
1) Start with the v1Path foo.com/bar/baz.
2) Trim off the version series path foo.com/bar to get 'baz'.
3) Join with the versioned module path foo.com/bar/v2 to get
foo.com/bar/v2/baz.
...being careful about slashes along the way.
pathNotFoundError returns a page with an option on how to
add a package or module to the site.
pollForPath polls the database until a row for fullPath is found.
prev returns the number of the page before the given page, or zero if the
given page is 1 or smaller.
previousFetchStatusAndResponse returns the fetch result from a
previous fetch of the fullPath and requestedVersion.
pseudoVersionRev extracts the pseudo version base, excluding the timestamp.
It assumes the pseudo version is correctly formatted.
See TestPseudoVersionBase for examples.
pseudoVersionRev extracts the first 7 characters of the commit identifier
from a pseudo version string. It assumes the pseudo version is correctly
formatted.
readmeContent renders the readme to html and collects the headings
into an outline.
resultFromFetchRequest returns the HTTP status code and response
text from the results of fetching possible module paths for fullPath at the
requestedVersion. It is assumed the results are sorted in order of
decreasing modulePath length, so the first result that is not a
StatusNotFound is returned. If all of the results are 404, but a module
path was found that shares the path prefix of fullPath, the responseText will
contain that information. The status and responseText will be displayed to the
user.
sanitizeHTML sanitizes HTML from a bytes.Buffer so that it is safe.
searchQuery extracts a search query from the request.
searchRequestRedirectPath returns the path that a search request should be
redirected to, or the empty string if there is no such path. If the user
types an existing package path into the search bar, we will redirect the
user to the details page. Standard library packages that only contain one
element (such as fmt, errors, etc.) will not redirect, to allow users to
search by those terms.
section collects all lines with the same prefix into a section. It assumes
that lines is sorted. It returns the section along with the remaining lines.
shorten shortens the string s to maxLen by removing the trailing characters.
shortRationale returns a rationale string that is safe
to print in a terminal. It returns hard-coded strings if the rationale
is empty, too long, or contains non-printable characters.
sortSymbols returns an array of symbols in order of
(1) Constants (2) Variables (3) Functions and (4) Types.
Within each section, symbols are sorted alphabetically by name.
In the types sections, aside from interfaces, child symbols are sorted in
order of (1) Fields (2) Constants (3) Variables (4) Functions and (5)
Methods. For interfaces, child symbols are sorted in order of
(1) Methods (2) Constants (3) Variables and (4) Functions.
styleGuide collects the paths to the markdown files in content/static,
renders them into sections for the styleguide, and merges the document
outlines into a single page outline.
styleSection uses goldmark to parse a markdown file and render
a section of the styleguide.
symbolsForVersions returns an array of symbols for use in the VersionSummary
of the specified version.
transformLicenseMetadata transforms licenses.Metadata into a LicenseMetadata
by adding an anchor field.
transformLicenses transforms licenses.License into a License
by adding an anchor field.
translateHTML parses html text into parsed html nodes. It then
iterates through the nodes and replaces the src key with a value
that properly represents the source of the image from the repo.
translateLink converts image links so that they will work on pkgsite.
README files sometimes use relative image paths to image files inside the
repository. As the discovery site doesn't host the full repository content,
in order for the image to render, we need to convert the relative path to an
absolute URL to a hosted image.
In addition, GitHub will translate absolute non-raw links to image files to raw links.
For example, when GitHub renders a README with
<img src="https://github.com/gobuffalo/buffalo/blob/master/logo.svg">
it rewrites it to
<img src="https://github.com/gobuffalo/buffalo/raw/master/logo.svg">
(replacing "blob" with "raw").
We do that too.
trimmedEscapedPath trims surrounding whitespace from u's path, then returns it escaped.
unitDirectories zips the subdirectories and nested modules together in a two
level tree hierarchy.
walkHTML crawls through an html node and replaces the src
tag link with a link that properly represents the image
from the repo source.
It reports whether it made a change.
Package-Level Variables (total 23, in which 3 are exported)
FetchLatencyDistribution aggregates frontend fetch request
latency by status code.
FetchResponseCount counts frontend fetch responses by response type.
errModuleDoesNotExist indicates that we have attempted to fetch the
module, and the proxy returned a status 404/410. There is a row for
this module version in version_map.
errPathDoesNotExistInModule indicates that a module for the path prefix
exists, but within that module version, this fullPath could not be found.
errUnitNotFoundWithoutFetch returns a 404 with instructions to the user on
how to manually fetch the package. No fetch button is provided. This is used
for very large modules or modules that previously 500ed.
maxPathsToFetch is the number of modulePaths that are fetched from a single
fetch request. The longest module path we've seen in our database had 7 path
elements. maxPathsToFetch is set to 10 as a buffer.
playgroundURL is the playground endpoint used for share links.
defaultTTL is used when details tab contents are subject to change, or when
there is a problem confirming that the details can be permanently cached.
The name of the heading from which we extract links.
longTTL is used when details content is essentially static.
maxSearchOffset is the maximum allowed offset into the search results.
This prevents some very CPU-intensive queries from running.
maxSearchPageSize is the maximum allowed limit for search results.
maxSearchQueryLength represents the max number of characters that a search
query can be. For PostgreSQL 11, there is a max length of 2K bytes:
https://www.postgresql.org/docs/11/textsearch-limitations.html. No valid
searches on pkg.go.dev will need more than the maxSearchQueryLength.
The pages are generated with Goldsv0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.
