Back to

Package internal

Latest Go to latest

The latest major version is .

Published: 1 day ago | License: BSD-3-Clause | Module:


Package internal contains data used through x/pkgsite.



const (
	// LatestVersion signifies the latest available version in requests to the
	// proxy client.
	LatestVersion = "latest"

	// MasterVersion signifies the version at master.
	MasterVersion = "master"

	// UnknownModulePath signifies that the module path for a given package
	// path is ambiguous or not known. This is because requests to the
	// frontend can come in the form of <import-path>[@<version>], and it is
	// not clear which part of the import-path is the module path.
	UnknownModulePath = "unknownModulePath"
const (
	ExperimentAltRequeue          = "alt-requeue"
	ExperimentAutocomplete        = "autocomplete"
	ExperimentFrontendRenderDoc   = "frontend-render-doc"
	ExperimentGetUnitWithOneQuery = "get-unit-with-one-query"
	ExperimentGoldmark            = "goldmark"
	ExperimentInsertPackageSource = "insert-package-source"
	ExperimentRemoveUnusedAST     = "remove-unused-ast"
	ExperimentSidenav             = "sidenav"
	ExperimentUnitPage            = "unit-page"
const StringFieldMissing = "!MISSING"

StringFieldMissing is the value for string fields that are not present in a struct. We use it to distinguish a (possibly valid) empty string from a field that was never populated.


var Experiments = map[string]string{
	ExperimentAltRequeue:          "Requeue modules for reprocessing in a different order.",
	ExperimentAutocomplete:        "Enable autocomplete with search.",
	ExperimentFrontendRenderDoc:   "Render documentation on the frontend if possible.",
	ExperimentGetUnitWithOneQuery: "Fetch data for GetUnit using a single query.",
	ExperimentGoldmark:            "Enable the usage of rendering markdown using goldmark instead of blackfriday.",
	ExperimentInsertPackageSource: "Insert the source code of a package in the database.",
	ExperimentRemoveUnusedAST:     "Prune AST prior to rendering documentation HTML.",
	ExperimentSidenav:             "Display documentation index on the left sidenav.",
	ExperimentUnitPage:            "Enable the redesigned details page.",

Experiments represents all of the active experiments in the codebase and a description of each experiment.

func SeriesPathForModule

func SeriesPathForModule(modulePath string) string

SeriesPathForModule returns the series path for the provided modulePath.

func Suffix

func Suffix(fullPath, basePath string) string

Suffix returns the suffix of the fullPath. It assumes that basePath is a prefix of fullPath. If fullPath and basePath are the same, the empty string is returned.

func V1Path

func V1Path(fullPath, modulePath string) string

V1Path returns the path for version 1 of the package whose import path is fullPath. If modulePath is the standard library, then V1Path returns fullPath.

type DataSource

type DataSource interface {

	// GetLatestMajorVersion returns the latest major version of a series path.
	GetLatestMajorVersion(ctx context.Context, seriesPath string) (_ string, err error)
	// GetNestedModules returns the latest major version of all nested modules
	// given a modulePath path prefix.
	GetNestedModules(ctx context.Context, modulePath string) ([]*ModuleInfo, error)
	// GetUnit returns information about a directory, which may also be a
	// module and/or package. The module and version must both be known.
	GetUnit(ctx context.Context, pathInfo *UnitMeta, fields FieldSet) (_ *Unit, err error)
	// GetUnitMeta returns information about a path.
	GetUnitMeta(ctx context.Context, path, requestedModulePath, requestedVersion string) (_ *UnitMeta, err error)

DataSource is the interface used by the frontend to interact with module data.

type Documentation

type Documentation struct {
	// The values of the GOOS and GOARCH environment variables used to parse the
	// package.
	GOOS     string
	GOARCH   string
	Synopsis string
	HTML     safehtml.HTML
	Source   []byte // encoded ast.Files; see godoc.Package.Encode

Documentation is the rendered documentation for a given package for a specific GOOS and GOARCH.

type Experiment

type Experiment struct {

	// Name is the name of the feature.
	Name string

	// Rollout is the percentage of requests enrolled in the experiment.
	Rollout uint

	// Description provides a description of the experiment.
	Description string

Experiment holds data associated with an experimental feature for frontend or worker.

type FieldSet

type FieldSet int64

A FieldSet is a bit set of struct fields. It is used to avoid reading large struct fields from the data store. FieldSet is also the type of the individual bit values. (Think of them as singleton sets.)

MinimalFields (the zero value) is the empty set. AllFields is the set containing every field.

FieldSet bits are unique across the entire project, because some types are concatenations (via embedding) of others. For example, a

const (
	WithReadme FieldSet = 1 << iota

FieldSet bits for fields that can be conditionally read from the data store.

const AllFields FieldSet = -1

AllFields is the FieldSet that contains all fields.

const MinimalFields FieldSet = 0

MinimalFields is the empty FieldSet.

type IndexVersion

type IndexVersion struct {
	Path      string
	Version   string
	Timestamp time.Time

IndexVersion holds the version information returned by the module index.

type LegacyDirectory

type LegacyDirectory struct {
	Path     string
	Packages []*LegacyPackage

LegacyDirectory represents a directory in a module version, and all of the packages inside that directory.

func (*LegacyDirectory) RemoveNonRedistributableData

func (d *LegacyDirectory) RemoveNonRedistributableData()

type LegacyPackage

type LegacyPackage struct {
	Path              string
	Name              string
	Synopsis          string
	IsRedistributable bool
	Licenses          []*licenses.Metadata // metadata of applicable licenses
	Imports           []string
	DocumentationHTML safehtml.HTML
	// The values of the GOOS and GOARCH environment variables used to parse the
	// package.
	GOOS   string
	GOARCH string

	// V1Path is the package path of a package with major version 1 in a given
	// series.
	V1Path string

A LegacyPackage is a group of one or more Go source files with the same package header.

func (*LegacyPackage) RemoveNonRedistributableData

func (p *LegacyPackage) RemoveNonRedistributableData()

type Module

type Module struct {
	// Licenses holds all licenses within this module version, including those
	// that may be contained in nested subdirectories.
	Licenses []*licenses.License
	Units    []*Unit

A Module is a specific, reproducible build of a module.

func (*Module) Packages

func (m *Module) Packages() []*Unit

Packages returns all of the units for a module that are packages.

func (*Module) RemoveNonRedistributableData

func (m *Module) RemoveNonRedistributableData()

type ModuleInfo

type ModuleInfo struct {
	ModulePath        string
	Version           string
	CommitTime        time.Time
	IsRedistributable bool
	HasGoMod          bool // whether the module zip has a go.mod file
	SourceInfo        *source.Info

ModuleInfo holds metadata associated with a module.

func (*ModuleInfo) SeriesPath

func (v *ModuleInfo) SeriesPath() string

SeriesPath returns the series path for the module.

A series is a group of modules that share the same base path and are assumed to be major-version variants.

The series path is the module path without the version. For most modules, this will be the module path for all module versions with major version 0 or 1. For modules, the series path does not correspond to any module version.

Examples: The module paths "a/b" and "a/b/v2" both have series path "a/b". The module paths "" and "" both have series path "".

type ModuleVersionState

type ModuleVersionState struct {
	ModulePath string
	Version    string

	// IndexTimestamp is the timestamp received from the Index for this version,
	// which should correspond to the time this version was committed to the
	// Index.
	IndexTimestamp time.Time
	// CreatedAt is the time this version was originally inserted into the
	// module version state table.
	CreatedAt time.Time

	// Status is the most recent HTTP status code received from the Fetch service
	// for this version, or nil if no request to the fetch service has been made.
	Status int
	// Error is the most recent HTTP response body received from the Fetch
	// service, for a response with an unsuccessful status code. It is used for
	// debugging only, and has no semantic significance.
	Error string
	// TryCount is the number of times a fetch of this version has been
	// attempted.
	TryCount int
	// LastProcessedAt is the last time this version was updated with a result
	// from the fetch service.
	LastProcessedAt *time.Time
	// NextProcessedAfter is the next time a fetch for this version should be
	// attempted.
	NextProcessedAfter time.Time

	// AppVersion is the value of the GAE_VERSION environment variable, which is
	// set by app engine. It is a timestamp in the format 20190709t112655 that
	// is close to, but not the same as, the deployment time. For example, the
	// deployment time for the above timestamp might be Jul 9, 2019, 11:29:59 AM.
	AppVersion string

	// GoModPath is the path declared in the go.mod file.
	GoModPath string

	// NumPackages it the number of packages that were processed as part of the
	// module (regardless of whether the processing was successful).
	NumPackages *int

ModuleVersionState holds a worker module version state.

type PackageMeta

type PackageMeta struct {
	Path              string
	Name              string
	Synopsis          string
	IsRedistributable bool
	Licenses          []*licenses.Metadata // metadata of applicable licenses

PackageMeta represents the metadata of a package in a module version.

func (*PackageMeta) RemoveNonRedistributableData

func (p *PackageMeta) RemoveNonRedistributableData()

type PackageVersionState

type PackageVersionState struct {
	PackagePath string
	ModulePath  string
	Version     string
	Status      int
	Error       string

PackageVersionState holds a worker package version state. It is associated with a given module version state.

type Readme

type Readme struct {
	Filepath string
	Contents string

Readme is a README at the specified filepath.

type SearchResult

type SearchResult struct {
	Name        string
	PackagePath string
	ModulePath  string
	Version     string
	Synopsis    string
	Licenses    []string

	CommitTime time.Time
	// Score is used to sort items in an array of SearchResult.
	Score float64

	// NumImportedBy is the number of packages that import PackagePath.
	NumImportedBy uint64

	// NumResults is the total number of packages that were returned for this
	// search.
	NumResults uint64
	// Approximate reports whether NumResults is an approximate count. NumResults
	// can be approximate if search scanned only a subset of documents, and
	// result count is estimated using the hyperloglog algorithm.
	Approximate bool

SearchResult represents a single search result from SearchDocuments.

type Unit

type Unit struct {
	Readme          *Readme
	Documentation   *Documentation
	Subdirectories  []*PackageMeta
	Imports         []string
	LicenseContents []*licenses.License
	NumImports      int
	NumImportedBy   int

Unit represents the contents of some path in the Go package/module namespace. It might be a module, a package, both a module and a package, or none of the above: a directory within a module that has no .go files, but contains other units, licenses and/or READMEs."

func (*Unit) RemoveNonRedistributableData

func (u *Unit) RemoveNonRedistributableData()

type UnitMeta

type UnitMeta struct {
	// Unit level information
	Path              string
	Name              string
	IsRedistributable bool
	Licenses          []*licenses.Metadata

	// Module level information
	Version    string
	ModulePath string
	CommitTime time.Time
	SourceInfo *source.Info

UnitMeta represents metadata about a unit.

func (*UnitMeta) IsCommand

func (um *UnitMeta) IsCommand() bool

IsCommand reports whether the path represents a package path.

func (*UnitMeta) IsModule

func (um *UnitMeta) IsModule() bool

IsModule reports whether the path represents a module path.

func (*UnitMeta) IsPackage

func (um *UnitMeta) IsPackage() bool

IsPackage reports whether the path represents a package path.

type VersionMap

type VersionMap struct {
	ModulePath       string
	RequestedVersion string
	ResolvedVersion  string
	GoModPath        string
	Status           int
	Error            string
	UpdatedAt        time.Time

VersionMap holds metadata associated with module queries for a version.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier