module

Documentation

Overview

Package module defines the module.Version type along with support code.

The module.Version type is a simple Path, Version pair:

type Version struct {
	Path string
	Version string
}

There are no restrictions imposed directly by use of this structure, but additional checking functions, most notably Check, verify that a particular path, version pair is valid.

Escaped Paths

Module paths appear as substrings of file system paths (in the download cache) and of web server URLs in the proxy protocol. In general we cannot rely on file systems to be case-sensitive, nor can we rely on web servers, since they read from file systems. That is, we cannot rely on the file system to keep rsc.io/QUOTE and rsc.io/quote separate. Windows and macOS don't. Instead, we must never require two different casings of a file path. Because we want the download cache to match the proxy protocol, and because we want the proxy protocol to be possible to serve from a tree of static files (which might be stored on a case-insensitive file system), the proxy protocol must never require two different casings of a URL path either.

One possibility would be to make the escaped form be the lowercase hexadecimal encoding of the actual path bytes. This would avoid ever needing different casings of a file path, but it would be fairly illegible to most programmers when those paths appeared in the file system (including in file paths in compiler errors and stack traces) in web server logs, and so on. Instead, we want a safe escaped form that leaves most paths unaltered.

The safe escaped form is to replace every uppercase letter with an exclamation mark followed by the letter's lowercase equivalent.

For example,

github.com/Azure/azure-sdk-for-go ->  github.com/!azure/azure-sdk-for-go.
github.com/GoogleCloudPlatform/cloudsql-proxy -> github.com/!google!cloud!platform/cloudsql-proxy
github.com/Sirupsen/logrus -> github.com/!sirupsen/logrus.

Import paths that avoid upper-case letters are left unchanged. Note that because import paths are ASCII-only and avoid various problematic punctuation (like : < and >), the escaped form is also ASCII-only and avoids the same problematic punctuation.

Import paths have never allowed exclamation marks, so there is no need to define how to escape a literal !.

Unicode Restrictions

Today, paths are disallowed from using Unicode.

Although paths are currently disallowed from using Unicode, we would like at some point to allow Unicode letters as well, to assume that file systems and URLs are Unicode-safe (storing UTF-8), and apply the !-for-uppercase convention for escaping them in the file system. But there are at least two subtle considerations.

First, note that not all case-fold equivalent distinct runes form an upper/lower pair. For example, U+004B ('K'), U+006B ('k'), and U+212A ('K' for Kelvin) are three distinct runes that case-fold to each other. When we do add Unicode letters, we must not assume that upper/lower are the only case-equivalent pairs. Perhaps the Kelvin symbol would be disallowed entirely, for example. Or perhaps it would escape as "!!k", or perhaps as "(212A)".

Second, it would be nice to allow Unicode marks as well as letters, but marks include combining marks, and then we must deal not only with case folding but also normalization: both U+00E9 ('é') and U+0065 U+0301 ('e' followed by combining acute accent) look the same on the page and are treated by some file systems as the same path. If we do allow Unicode marks in paths, there must be some kind of normalization to allow only one canonical encoding of any character used in an import path.

Index

• Constants
• func CanonicalVersion(v string) string
• func Check(path, version string) error
• func CheckFilePath(path string) error
• func CheckImportPath(path string) error
• func CheckPath(path string) (err error)
• func CheckPathMajor(v, pathMajor string) error
• func EscapePath(path string) (escaped string, err error)
• func EscapeVersion(v string) (escaped string, err error)
• func IsPseudoVersion(v string) bool
• func IsZeroPseudoVersion(v string) bool
• func MatchPathMajor(v, pathMajor string) bool
• func MatchPrefixPatterns(globs, target string) bool
• func PathMajorPrefix(pathMajor string) string
• func PseudoVersion(major, older string, t time.Time, rev string) string
• func PseudoVersionBase(v string) (string, error)
• func PseudoVersionRev(v string) (rev string, err error)
• func PseudoVersionTime(v string) (time.Time, error)
• func Sort(list []Version)
• func SplitPathVersion(path string) (prefix, pathMajor string, ok bool)
• func UnescapePath(escaped string) (path string, err error)
• func UnescapeVersion(escaped string) (v string, err error)
• func VersionError(v Version, err error) error
• func ZeroPseudoVersion(major string) string
• type InvalidPathError
  • func (e *InvalidPathError) Error() string
  • func (e *InvalidPathError) Unwrap() error
• type InvalidVersionError
  • func (e *InvalidVersionError) Error() string
  • func (e *InvalidVersionError) Unwrap() error
• type ModuleError
  • func (e *ModuleError) Error() string
  • func (e *ModuleError) Unwrap() error
• type Version
  • func (m Version) String() string

Constants

const PseudoVersionTimestampFormat = "20060102150405"

Functions

func CanonicalVersion

func CanonicalVersion(v string) string

CanonicalVersion returns the canonical form of the version string v. It is the same as semver.Canonical except that it preserves the special build suffix "+incompatible".

func Check

func Check(path, version string) error

Check checks that a given module path, version pair is valid. In addition to the path being a valid module path and the version being a valid semantic version, the two must correspond. For example, the path "yaml/v2" only corresponds to semantic versions beginning with "v2.".

func CheckFilePath

func CheckFilePath(path string) error

CheckFilePath checks that a slash-separated file path is valid. The definition of a valid file path is the same as the definition of a valid import path except that the set of allowed characters is larger: all Unicode letters, ASCII digits, the ASCII space character (U+0020), and the ASCII punctuation characters “!#$%&()+,-.=@[]^_{}~”. (The excluded punctuation characters, " * < > ? ` ' | / \ and :, have special meanings in certain shells or operating systems.)

CheckFilePath may be less restrictive in the future, but see the top-level package documentation for additional information about subtleties of Unicode.

func CheckImportPath

func CheckImportPath(path string) error

CheckImportPath checks that an import path is valid.

A valid import path consists of one or more valid path elements separated by slashes (U+002F). (It must not begin with nor end in a slash.)

A valid path element is a non-empty string made up of ASCII letters, ASCII digits, and limited ASCII punctuation: - . _ and ~. It must not end with a dot (U+002E), nor contain two dots in a row.

The element prefix up to the first dot must not be a reserved file name on Windows, regardless of case (CON, com1, NuL, and so on). The element must not have a suffix of a tilde followed by one or more ASCII digits (to exclude paths elements that look like Windows short-names).

CheckImportPath may be less restrictive in the future, but see the top-level package documentation for additional information about subtleties of Unicode.

func CheckPath

func CheckPath(path string) (err error)

CheckPath checks that a module path is valid. A valid module path is a valid import path, as checked by CheckImportPath, with three additional constraints. First, the leading path element (up to the first slash, if any), by convention a domain name, must contain only lower-case ASCII letters, ASCII digits, dots (U+002E), and dashes (U+002D); it must contain at least one dot and cannot start with a dash. Second, for a final path element of the form /vN, where N looks numeric (ASCII digits and dots) must not begin with a leading zero, must not be /v1, and must not contain any dots. For paths beginning with "gopkg.in/", this second requirement is replaced by a requirement that the path follow the gopkg.in server's conventions. Third, no path element may begin with a dot.

func CheckPathMajor

func CheckPathMajor(v, pathMajor string) error

CheckPathMajor returns a non-nil error if the semantic version v does not match the path major version pathMajor.

func EscapePath

func EscapePath(path string) (escaped string, err error)

EscapePath returns the escaped form of the given module path. It fails if the module path is invalid.

func EscapeVersion

func EscapeVersion(v string) (escaped string, err error)

EscapeVersion returns the escaped form of the given module version. Versions are allowed to be in non-semver form but must be valid file names and not contain exclamation marks.

func IsPseudoVersion

func IsPseudoVersion(v string) bool

IsPseudoVersion reports whether v is a pseudo-version.

func IsZeroPseudoVersion

func IsZeroPseudoVersion(v string) bool

IsZeroPseudoVersion returns whether v is a pseudo-version with a zero base, timestamp, and revision, as returned by ZeroPseudoVersion.

func MatchPathMajor

func MatchPathMajor(v, pathMajor string) bool

MatchPathMajor reports whether the semantic version v matches the path major version pathMajor.

MatchPathMajor returns true if and only if CheckPathMajor returns nil.

func MatchPrefixPatterns

func MatchPrefixPatterns(globs, target string) bool

MatchPrefixPatterns reports whether any path prefix of target matches one of the glob patterns (as defined by path.Match) in the comma-separated globs list. This implements the algorithm used when matching a module path to the GOPRIVATE environment variable, as described by 'go help module-private'.

It ignores any empty or malformed patterns in the list. Trailing slashes on patterns are ignored.

func PathMajorPrefix

func PathMajorPrefix(pathMajor string) string

PathMajorPrefix returns the major-version tag prefix implied by pathMajor. An empty PathMajorPrefix allows either v0 or v1.

Note that MatchPathMajor may accept some versions that do not actually begin with this prefix: namely, it accepts a 'v0.0.0-' prefix for a '.v1' pathMajor, even though that pathMajor implies 'v1' tagging.

func PseudoVersion

func PseudoVersion(major, older string, t time.Time, rev string) string

PseudoVersion returns a pseudo-version for the given major version ("v1") preexisting older tagged version ("" or "v1.2.3" or "v1.2.3-pre"), revision time, and revision identifier (usually a 12-byte commit hash prefix).

func PseudoVersionBase

func PseudoVersionBase(v string) (string, error)

PseudoVersionBase returns the canonical parent version, if any, upon which the pseudo-version v is based.

If v has no parent version (that is, if it is "vX.0.0-[…]"), PseudoVersionBase returns the empty string and a nil error.

func PseudoVersionRev

func PseudoVersionRev(v string) (rev string, err error)

PseudoVersionRev returns the revision identifier of the pseudo-version v. It returns an error if v is not a pseudo-version.

func PseudoVersionTime

func PseudoVersionTime(v string) (time.Time, error)

PseudoVersionTime returns the time stamp of the pseudo-version v. It returns an error if v is not a pseudo-version or if the time stamp embedded in the pseudo-version is not a valid time.

func Sort

func Sort(list []Version)

Sort sorts the list by Path, breaking ties by comparing Version fields. The Version fields are interpreted as semantic versions (using semver.Compare) optionally followed by a tie-breaking suffix introduced by a slash character, like in "v0.0.1/go.mod".

func SplitPathVersion

func SplitPathVersion(path string) (prefix, pathMajor string, ok bool)

SplitPathVersion returns prefix and major version such that prefix+pathMajor == path and version is either empty or "/vN" for N >= 2. As a special case, gopkg.in paths are recognized directly; they require ".vN" instead of "/vN", and for all N, not just N >= 2. SplitPathVersion returns with ok = false when presented with a path whose last path element does not satisfy the constraints applied by CheckPath, such as "example.com/pkg/v1" or "example.com/pkg/v1.2".

func UnescapePath

func UnescapePath(escaped string) (path string, err error)

UnescapePath returns the module path for the given escaped path. It fails if the escaped path is invalid or describes an invalid path.

func UnescapeVersion

func UnescapeVersion(escaped string) (v string, err error)

UnescapeVersion returns the version string for the given escaped version. It fails if the escaped form is invalid or describes an invalid version. Versions are allowed to be in non-semver form but must be valid file names and not contain exclamation marks.

func VersionError

func VersionError(v Version, err error) error

VersionError returns a ModuleError derived from a Version and error, or err itself if it is already such an error.

func ZeroPseudoVersion

func ZeroPseudoVersion(major string) string

ZeroPseudoVersion returns a pseudo-version with a zero timestamp and revision, which may be used as a placeholder.

Types

type InvalidPathError

type InvalidPathError struct {
	Kind string // "module", "import", or "file"
	Path string
	Err  error
}

An InvalidPathError indicates a module, import, or file path doesn't satisfy all naming constraints. See CheckPath, CheckImportPath, and CheckFilePath for specific restrictions.

func (*InvalidPathError) Error

func (e *InvalidPathError) Error() string

func (*InvalidPathError) Unwrap

func (e *InvalidPathError) Unwrap() error

type InvalidVersionError

type InvalidVersionError struct {
	Version string
	Pseudo  bool
	Err     error
}

An InvalidVersionError indicates an error specific to a version, with the module path unknown or specified externally.

A ModuleError may wrap an InvalidVersionError, but an InvalidVersionError must not wrap a ModuleError.

func (*InvalidVersionError) Error

func (e *InvalidVersionError) Error() string

func (*InvalidVersionError) Unwrap

func (e *InvalidVersionError) Unwrap() error

type ModuleError

type ModuleError struct {
	Path    string
	Version string
	Err     error
}

A ModuleError indicates an error specific to a module.

func (*ModuleError) Error

func (e *ModuleError) Error() string

func (*ModuleError) Unwrap

func (e *ModuleError) Unwrap() error

type Version

type Version struct {
	// Path is a module path, like "golang.org/x/text" or "rsc.io/quote/v2".
	Path string

	// Version is usually a semantic version in canonical form.
	// There are three exceptions to this general rule.
	// First, the top-level target of a build has no specific version
	// and uses Version = "".
	// Second, during MVS calculations the version "none" is used
	// to represent the decision to take no version of a given module.
	// Third, filesystem paths found in "replace" directives are
	// represented by a path with an empty version.
	Version string `json:",omitempty"`
}

A Version (for clients, a module.Version) is defined by a module path and version pair. These are stored in their plain (unescaped) form.

func (Version) String

func (m Version) String() string

String returns a representation of the Version suitable for logging (Path@Version, or just Path if Version is empty).