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

404.go badge.go breadcrumb.go details.go doc.go fetch.go goldmark.go header.go imports.go latest_version.go license.go overview.go paginate.go playground.go readme.go redirect.go search.go section.go server.go tabs.go unit.go unit_main.go urlinfo.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: 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},
    }
)
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 LegacyReadmeHTML Uses

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

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.

func TagRoute Uses

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

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

type File Uses

type File struct {
    Name string
    URL  string
}

File is a source file for a package.

type Heading Uses

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
}

Heading holds data about a heading within a readme used in the sidebar template to render the readme outline.

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

    // Directories are packages and nested modules relative to the path for the
    // unit.
    Directories []*UnitDirectory

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

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

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

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 Uses

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

func (s *Server) GetLatestInfo(ctx context.Context, unitPath, modulePath string) 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 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
    IsModule bool
}

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

type UnitDirectory 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 *Subdirectory

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

UnitDirectory is the union of nested modules and subdirectories for a unit organized in a two level tree structure. This content is used in the directories section of the unit page.

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

    // 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 57 packages (graph) and is imported by 1 packages. Updated 2021-01-17. Refresh now. Tools for package owners.