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"
    ExperimentSidenav      = "sidenav"
    ExperimentUnitPage     = "unit-page"
    ExperimentUseUnits     = "use-units"
)

const StringFieldMissing = "!MISSING"

var Experiments = map[string]string{
    ExperimentAutocomplete: "Enable autocomplete with search.",
    ExperimentSidenav:      "Display documentation index on the left sidenav.",
    ExperimentUnitPage:     "Enable the redesigned details page.",
    ExperimentUseUnits:     "Read from paths, documentation, readmes, and package_imports tables.",
}

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)
    // GetUnitMeta returns information about a path.
    GetUnitMeta(ctx context.Context, path, requestedModulePath, requestedVersion string) (_ *UnitMeta, err 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)

    // 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)
    // LegacyGetImports returns a slice of import paths imported by the package
    // specified by path and version.
    LegacyGetImports(ctx context.Context, pkgPath, modulePath, version string) ([]string, error)
    // LegacyGetLicenses returns licenses at the given path for given modulePath and version.
    LegacyGetLicenses(ctx context.Context, fullPath, modulePath, resolvedVersion string) ([]*licenses.License, 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 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 FieldSet int64

const (
    WithReadme FieldSet = 1 << iota
    WithDocumentation
    WithImports
    WithLicenses
    WithSubdirectories
)

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 Module struct {
    LegacyModuleInfo
    // Licenses holds all licenses within this module version, including those
    // that may be contained in nested subdirectories.
    Licenses []*licenses.License
    Units    []*Unit

    LegacyPackages []*LegacyPackage
}

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
}

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 PackageMeta struct {
    Path              string
    Name              string
    Synopsis          string
    IsRedistributable bool
    Licenses          []*licenses.Metadata // metadata of applicable licenses
}

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 Unit struct {
    UnitMeta
    Readme          *Readme
    Documentation   *Documentation
    Subdirectories  []*PackageMeta
    Imports         []string
    LicenseContents []*licenses.License
}

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
}

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