pkgsite: golang.org/x/pkgsite/internal/frontend Index | Files

package frontend

import "golang.org/x/pkgsite/internal/frontend"

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

Index

Package Files

badge.go breadcrumb.go completion.go details.go directory.go doc.go fetch.go goldmark.go header.go imports.go latest_version.go license.go module.go overview.go package.go paginate.go playground.go search.go section.go server.go tabs.go unit.go unit_header.go unit_main.go unit_tabs.go versions.go

Variables

var (

    // FetchLatencyDistribution aggregates frontend fetch request
    // latency by status code.
    FetchLatencyDistribution = &view.View{
        Name:        "go-discovery/frontend-fetch/latency",
        Measure:     frontendFetchLatency,
        Aggregation: ochttp.DefaultLatencyDistribution,
        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},
    }
)
var (
    PlaygroundShareRequestCount = &view.View{
        Name:        "go-discovery/playground/share_count",
        Measure:     playgroundShareStatus,
        Aggregation: view.Count(),
        Description: "Playground share request count",
        TagKeys:     []tag.Key{keyPlaygroundShareStatus},
    }
)
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},
    }
)

func FetchAndUpdateState Uses

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 NewHTMLRenderer Uses

func NewHTMLRenderer(info *source.Info, readme *internal.Readme, opts ...html.Option) renderer.NodeRenderer

NewHTMLRenderer creates a new HTMLRenderer for a readme.

func ReadmeHTML Uses

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

ReadmeHTML 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.

It is exported to support external testing.

func TagRoute Uses

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

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

type ASTTransformer Uses

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

ASTTransformer is a default transformer of the goldmark tree. We pass in readme information to use for the link transformations.

func (*ASTTransformer) Transform Uses

func (g *ASTTransformer) Transform(node *ast.Document, reader text.Reader, pc parser.Context)

Transform transforms the given AST tree.

type DetailsPage Uses

type DetailsPage struct {

    // Name is the name of the package or command name, or the full
    // directory or module path.
    Name string

    // PageType is the type of page (pkg, cmd, dir, etc.).
    PageType string

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

    // Settings contains tab-specific metadata.
    Settings TabSettings

    // Details contains data specific to the type of page being rendered.
    Details interface{}

    // Header contains data to be rendered in the heading of all details pages.
    Header interface{}

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

    // Tabs contains data to render the varioius tabs on each details page.
    Tabs []TabSettings

    // CanonicalURLPath is the representation of the URL path for the details
    // page, after the requested version and module path have been resolved.
    // For example, if the latest version of /my.module/pkg is version v1.5.2,
    // the canonical url for that path would be /my.module@v1.5.2/pkg
    CanonicalURLPath string
    // contains filtered or unexported fields
}

DetailsPage contains data for a package of module details template.

type Directory Uses

type Directory struct {
    DirectoryHeader
    Packages      []*Package
    NestedModules []*internal.ModuleInfo
}

Directory contains information for an individual directory.

type DirectoryHeader Uses

type DirectoryHeader struct {
    Module
    Path string
    URL  string
}

DirectoryHeader contains information for the header on a directory page.

type DirectoryPage Uses

type DirectoryPage struct {
    *Directory
    // contains filtered or unexported fields
}

DirectoryPage contains data needed to generate a directory template.

type DocumentationDetails Uses

type DocumentationDetails struct {
    GOOS          string
    GOARCH        string
    Documentation safehtml.HTML
}

DocumentationDetails contains data for the doc template.

type File Uses

type File struct {
    Name string
    URL  string
}

File is a source file for a package.

type HTMLRenderer Uses

type HTMLRenderer struct {
    html.Config
    // contains filtered or unexported fields
}

HTMLRenderer is a renderer.NodeRenderer implementation that renders pkg.go.dev readme features.

func (*HTMLRenderer) RegisterFuncs Uses

func (r *HTMLRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)

RegisterFuncs implements renderer.NodeRenderer.RegisterFuncs.

type ImportedByDetails Uses

type ImportedByDetails struct {
    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

    Total        int  // number of packages in ImportedBy
    TotalIsExact bool // if false, then there may be more than Total
}

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

type ImportsDetails Uses

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 Uses

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

License contains information used for a single license section.

type LicenseMetadata Uses

type LicenseMetadata struct {
    Type   string
    Anchor safehtml.Identifier
}

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

type LicensesDetails Uses

type LicensesDetails struct {
    Licenses []License
}

LicensesDetails contains license information for a package or module.

type MainDetails Uses

type MainDetails struct {
    // NestedModules are nested modules relative to the path for the unit.
    NestedModules []*NestedModule

    // Subdirectories are packages in subdirectories relative to the path for
    // the unit.
    Subdirectories []*Subdirectory

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

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

    // 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

    // 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

    // 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
}

MainDetails contains data needed to render the unit template.

type Module Uses

type Module struct {
    DisplayVersion    string
    LinkVersion       string
    ModulePath        string
    CommitTime        string
    IsRedistributable bool
    URL               string // relative to this site
    LatestURL         string // link with latest-version placeholder, relative to this site
    Licenses          []LicenseMetadata
}

Module contains information for an individual module.

type NestedModule Uses

type NestedModule struct {
    Suffix string // suffix after the unit path
    URL    string
}

NestedModule is a nested module relative to the path of a given unit. This content is used in the Directories section of the unit page.

type OverviewDetails Uses

type OverviewDetails struct {
    ModulePath       string
    ModuleURL        string
    PackageSourceURL string
    ReadMe           safehtml.HTML
    ReadMeSource     string
    Redistributable  bool
    RepositoryURL    string
}

OverviewDetails contains all of the data that the readme template needs to populate.

type Package Uses

type Package struct {
    Module
    Path               string // full import path
    URL                string // relative to this site
    LatestURL          string // link with latest-version placeholder, relative to this site
    IsRedistributable  bool
    Licenses           []LicenseMetadata
    PathAfterDirectory string // for display on the directories tab; used by Directory
    Synopsis           string // for display on the directories tab; used by Directory
}

Package contains information for an individual package.

type SearchPage Uses

type SearchPage struct {
    Pagination pagination
    Results    []*SearchResult
    // contains filtered or unexported fields
}

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

type SearchResult Uses

type SearchResult struct {
    Name           string
    PackagePath    string
    ModulePath     string
    Synopsis       string
    DisplayVersion string
    Licenses       []string
    CommitTime     string
    NumImportedBy  uint64
    Approximate    bool
}

SearchResult contains data needed to display a single search result.

type Section Uses

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 Uses

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 Uses

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

Server can be installed to serve the go discovery frontend.

func NewServer Uses

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

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

func (*Server) GetLatestMajorVersion Uses

func (s *Server) GetLatestMajorVersion(ctx context.Context, seriesPath string) string

GetLatestMajorVersion returns the major version of a package or module. If a module isn't found from the series path or an error ocurs, an empty string is returned It is intended to be used as an argument to middleware.LatestVersions.

func (*Server) GetLatestMinorVersion Uses

func (s *Server) GetLatestMinorVersion(ctx context.Context, packagePath, modulePath, pageType string) string

GetLatestMinorVersion returns the latest minor version of the package or module. The linkable form of the minor version is returned and is an empty string on error. It is intended to be used as an argument to middleware.LatestVersions.

func (*Server) Install Uses

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) PanicHandler Uses

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 Uses

type ServerConfig struct {
    // DataSourceGetter should return a DataSource on each call.
    // It should be goroutine-safe.
    DataSourceGetter     func(context.Context) internal.DataSource
    Queue                queue.Queue
    CompletionClient     *redis.Client
    TaskIDChangeInterval time.Duration
    StaticPath           template.TrustedSource
    ThirdPartyPath       string
    DevMode              bool
    AppVersionLabel      string
    GoogleTagManagerID   string
    ServeStats           bool
}

ServerConfig contains everything needed by a Server.

type Subdirectory Uses

type Subdirectory struct {
    Suffix   string
    URL      string
    Synopsis string
}

Subdirectory is a package in a subdirectory relative to the path of a given unit. This content is used in the Directories section of the unit page.

type TabSettings Uses

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 Uses

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

    // 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

    // Tabs contains data to render the varioius tabs on each details page.
    Tabs []TabSettings

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

    // Details contains data specific to the type of page being rendered.
    Details interface{}
    // contains filtered or unexported fields
}

UnitPage contains data needed to render the unit template.

type VersionList Uses

type VersionList struct {
    VersionListKey
    // 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 Uses

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
}

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.

type VersionSummary Uses

type VersionSummary struct {
    CommitTime string
    // Link to this version, for use in the anchor href.
    Link    string
    Version string
}

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

type VersionsDetails Uses

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

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

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.

Package frontend imports 55 packages (graph) and is imported by 1 packages. Updated 2020-10-28. Refresh now. Tools for package owners.