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 (
    ExperimentAutocomplete          = "autocomplete"
    ExperimentFrontendFetch         = "frontend-fetch"
    ExperimentInsertPlaygroundLinks = "insert-playground-links"
    ExperimentMasterVersion         = "master-version"
    ExperimentSidenav               = "sidenav"
    ExperimentTranslateHTML         = "translate-html"
    ExperimentUseDirectories        = "use-directories"
    ExperimentUsePackageImports     = "use-package-imports"
    ExperimentUsePathInfo           = "use-path-info"
)

const StringFieldMissing = "!MISSING"

var Experiments = map[string]string{
    ExperimentAutocomplete:          "Enable autocomplete with search.",
    ExperimentFrontendFetch:         "Enable ability to fetch a package that doesn't exist on pkg.go.dev.",
    ExperimentInsertPlaygroundLinks: "Insert Go playground links for examples.",
    ExperimentMasterVersion:         "Enable viewing path@master.",
    ExperimentSidenav:               "Display documentation index on the left sidenav.",
    ExperimentTranslateHTML:         "Parse HTML text in READMEs, to properly display images.",
    ExperimentUseDirectories:        "Read from paths, documentation, readmes, and package_imports tables.",
    ExperimentUsePathInfo:           "Check the paths table if a path exists, as opposed to the packages or modules table.",
    ExperimentUsePackageImports:     "Read imports from the package_imports table.",
}

type DataSource interface {

    // GetDirectory returns information about a directory, which may also be a module and/or package.
    // The module and version must both be known.
    GetDirectory(ctx context.Context, dirPath, modulePath, version string) (_ *VersionedDirectory, err error)
    // GetImports returns a slice of import paths imported by the package
    // specified by path and version.
    GetImports(ctx context.Context, pkgPath, modulePath, version string) ([]string, error)
    // GetLicenses returns licenses at the given path for given modulePath and version.
    GetLicenses(ctx context.Context, fullPath, modulePath, resolvedVersion string) ([]*licenses.License, error)
    // GetModuleInfo returns the ModuleInfo corresponding to modulePath and
    // version.
    GetModuleInfo(ctx context.Context, modulePath, version string) (*ModuleInfo, error)
    // GetPathInfo returns information about a path.
    GetPathInfo(ctx context.Context, path, inModulePath, inVersion string) (outModulePath, outVersion string, isPackage bool, err error)

    // TODO(golang/go#39629): Deprecate these methods.
    //
    // LegacyGetDirectory returns packages whose import path is in a (possibly
    // nested) subdirectory of the given directory path. When multiple
    // package paths satisfy this query, it should prefer the module with
    // the longest path.
    LegacyGetDirectory(ctx context.Context, dirPath, modulePath, version string, fields FieldSet) (_ *LegacyDirectory, err error)
    // LegacyGetModuleInfo returns the LegacyModuleInfo corresponding to modulePath and
    // version.
    LegacyGetModuleInfo(ctx context.Context, modulePath, version string) (*LegacyModuleInfo, error)
    // LegacyGetModuleLicenses returns all top-level Licenses for the given modulePath
    // and version. (i.e., Licenses contained in the module root directory)
    LegacyGetModuleLicenses(ctx context.Context, modulePath, version string) ([]*licenses.License, error)
    // LegacyGetPackage returns the LegacyVersionedPackage corresponding to the given package
    // pkgPath, modulePath, and version. When multiple package paths satisfy this query, it
    // should prefer the module with the longest path.
    LegacyGetPackage(ctx context.Context, pkgPath, modulePath, version string) (*LegacyVersionedPackage, error)
    // LegacyGetPackagesInModule returns LegacyPackages contained in the module version
    // specified by modulePath and version.
    LegacyGetPackagesInModule(ctx context.Context, modulePath, version string) ([]*LegacyPackage, error)
    // LegacyGetPackageLicenses returns all Licenses that apply to pkgPath, within the
    // module version specified by modulePath and version.
    LegacyGetPackageLicenses(ctx context.Context, pkgPath, modulePath, version string) ([]*licenses.License, error)
    // LegacyGetPsuedoVersionsForModule returns ModuleInfo for all known
    // pseudo-versions for the module corresponding to modulePath.
    LegacyGetPsuedoVersionsForModule(ctx context.Context, modulePath string) ([]*ModuleInfo, error)
    // LegacyGetPsuedoVersionsForModule returns ModuleInfo for all known
    // pseudo-versions for any module containing a package with the given import
    // path.
    LegacyGetPsuedoVersionsForPackageSeries(ctx context.Context, pkgPath string) ([]*ModuleInfo, error)
    // LegacyGetTaggedVersionsForModule returns ModuleInfo for all known tagged
    // versions for the module corresponding to modulePath.
    LegacyGetTaggedVersionsForModule(ctx context.Context, modulePath string) ([]*ModuleInfo, error)
    // LegacyGetTaggedVersionsForModule returns ModuleInfo for all known tagged
    // versions for any module containing a package with the given import path.
    LegacyGetTaggedVersionsForPackageSeries(ctx context.Context, pkgPath string) ([]*ModuleInfo, error)
}

type Directory struct {
    DirectoryMeta
    Readme  *Readme
    Package *Package
}

type DirectoryMeta struct {
    Path              string
    V1Path            string
    IsRedistributable bool
    Licenses          []*licenses.Metadata // metadata of applicable licenses
}

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
}

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
}

type ExperimentSource interface {
    // GetExperiments fetches active experiments from the
    // ExperimentSource.
    GetExperiments(ctx context.Context) ([]*Experiment, error)
}

type FieldSet int64

const (
    WithReadmeContents FieldSet = 1 << iota
    WithDocumentationHTML
)

const AllFields FieldSet = -1

const MinimalFields FieldSet = 0

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

type LegacyDirectory struct {
    LegacyModuleInfo
    Path     string
    Packages []*LegacyPackage
}

type LegacyModuleInfo struct {
    ModuleInfo
    LegacyReadmeFilePath string
    LegacyReadmeContents string
}

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
}

type LegacyVersionedPackage struct {
    LegacyPackage
    LegacyModuleInfo
}

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

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

    LegacyPackages []*LegacyPackage
}

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

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
}

type Package struct {
    Name          string
    Path          string
    Documentation *Documentation
    Imports       []string
}

type PackageMeta struct {
    DirectoryMeta
    Name     string
    Synopsis string
}

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

type Readme struct {
    Filepath string
    Contents string
}

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
}

type VersionMap struct {
    ModulePath       string
    RequestedVersion string
    ResolvedVersion  string
    GoModPath        string
    Status           int
    Error            string
}

type VersionedDirectory struct {
    Directory
    ModuleInfo
}