codehost

Documentation

Overview

Package codehost defines the interface implemented by a code hosting source, along with support code for use by implementations.

Index

• Constants
• Variables
• func AllHex(rev string) bool
• func Run(dir string, cmdline ...any) ([]byte, error)
• func RunWithStdin(dir string, stdin io.Reader, cmdline ...any) ([]byte, error)
• func ShortenSHA1(rev string) string
• func WorkDir(typ, name string) (dir, lockfile string, err error)
• type Origin
  • func (o *Origin) Checkable() bool
  • func (o *Origin) ClearCheckable()
• type Repo
  • func LocalGitRepo(remote string) (Repo, error)
  • func NewRepo(vcs, remote string) (Repo, error)
• type RevInfo
• type RunError
  • func (e *RunError) Error() string
• type Tag
• type Tags
• type UnknownRevisionError
  • func (e *UnknownRevisionError) Error() string
  • func (UnknownRevisionError) Is(err error) bool
• type VCSError
  • func (e *VCSError) Error() string
  • func (e *VCSError) Unwrap() error

Constants

const (
	MaxGoMod   = 16 << 20  // maximum size of go.mod file
	MaxLICENSE = 16 << 20  // maximum size of LICENSE file
	MaxZipFile = 500 << 20 // maximum size of downloaded zip file
)

Downloaded size limits.

Variables

var ErrNoCommits error = noCommitsError{}

ErrNoCommits is an error equivalent to fs.ErrNotExist indicating that a given repository or module contains no commits.

var ErrUnsupported = unsupportedOperationError{}

ErrUnsupported indicates that a requested operation cannot be performed, because it is unsupported. This error indicates that there is no alternative way to perform the operation.

TODO(#41198): Remove this declaration and use errors.ErrUnsupported instead.

Functions

func AllHex

func AllHex(rev string) bool

AllHex reports whether the revision rev is entirely lower-case hexadecimal digits.

func Run

func Run(dir string, cmdline ...any) ([]byte, error)

Run runs the command line in the given directory (an empty dir means the current directory). It returns the standard output and, for a non-zero exit, a *RunError indicating the command, exit status, and standard error. Standard error is unavailable for commands that exit successfully.

func RunWithStdin

func RunWithStdin(dir string, stdin io.Reader, cmdline ...any) ([]byte, error)

func ShortenSHA1

func ShortenSHA1(rev string) string

ShortenSHA1 shortens a SHA1 hash (40 hex digits) to the canonical length used in pseudo-versions (12 hex digits).

func WorkDir

func WorkDir(typ, name string) (dir, lockfile string, err error)

WorkDir returns the name of the cached work directory to use for the given repository type and name.

Types

type Origin

type Origin struct {
	VCS    string `json:",omitempty"` // "git" etc
	URL    string `json:",omitempty"` // URL of repository
	Subdir string `json:",omitempty"` // subdirectory in repo

	// If TagSum is non-empty, then the resolution of this module version
	// depends on the set of tags present in the repo, specifically the tags
	// of the form TagPrefix + a valid semver version.
	// If the matching repo tags and their commit hashes still hash to TagSum,
	// the Origin is still valid (at least as far as the tags are concerned).
	// The exact checksum is up to the Repo implementation; see (*gitRepo).Tags.
	TagPrefix string `json:",omitempty"`
	TagSum    string `json:",omitempty"`

	// If Ref is non-empty, then the resolution of this module version
	// depends on Ref resolving to the revision identified by Hash.
	// If Ref still resolves to Hash, the Origin is still valid (at least as far as Ref is concerned).
	// For Git, the Ref is a full ref like "refs/heads/main" or "refs/tags/v1.2.3",
	// and the Hash is the Git object hash the ref maps to.
	// Other VCS might choose differently, but the idea is that Ref is the name
	// with a mutable meaning while Hash is a name with an immutable meaning.
	Ref  string `json:",omitempty"`
	Hash string `json:",omitempty"`

	// If RepoSum is non-empty, then the resolution of this module version
	// failed due to the repo being available but the version not being present.
	// This depends on the entire state of the repo, which RepoSum summarizes.
	// For Git, this is a hash of all the refs and their hashes.
	RepoSum string `json:",omitempty"`
}

An Origin describes the provenance of a given repo method result. It can be passed to CheckReuse (usually in a different go command invocation) to see whether the result remains up-to-date.

func (*Origin) Checkable

func (o *Origin) Checkable() bool

Checkable reports whether the Origin contains anything that can be checked. If not, the Origin is purely informational and should fail a CheckReuse call.

func (*Origin) ClearCheckable

func (o *Origin) ClearCheckable()

ClearCheckable clears the Origin enough to make Checkable return false.

type Repo

type Repo interface {
	// CheckReuse checks whether the old origin information
	// remains up to date. If so, whatever cached object it was
	// taken from can be reused.
	// The subdir gives subdirectory name where the module root is expected to be found,
	// "" for the root or "sub/dir" for a subdirectory (no trailing slash).
	CheckReuse(old *Origin, subdir string) error

	// List lists all tags with the given prefix.
	Tags(prefix string) (*Tags, error)

	// Stat returns information about the revision rev.
	// A revision can be any identifier known to the underlying service:
	// commit hash, branch, tag, and so on.
	Stat(rev string) (*RevInfo, error)

	// Latest returns the latest revision on the default branch,
	// whatever that means in the underlying implementation.
	Latest() (*RevInfo, error)

	// ReadFile reads the given file in the file tree corresponding to revision rev.
	// It should refuse to read more than maxSize bytes.
	//
	// If the requested file does not exist it should return an error for which
	// os.IsNotExist(err) returns true.
	ReadFile(rev, file string, maxSize int64) (data []byte, err error)

	// ReadZip downloads a zip file for the subdir subdirectory
	// of the given revision to a new file in a given temporary directory.
	// It should refuse to read more than maxSize bytes.
	// It returns a ReadCloser for a streamed copy of the zip file.
	// All files in the zip file are expected to be
	// nested in a single top-level directory, whose name is not specified.
	ReadZip(rev, subdir string, maxSize int64) (zip io.ReadCloser, err error)

	// RecentTag returns the most recent tag on rev or one of its predecessors
	// with the given prefix. allowed may be used to filter out unwanted versions.
	RecentTag(rev, prefix string, allowed func(tag string) bool) (tag string, err error)

	// DescendsFrom reports whether rev or any of its ancestors has the given tag.
	//
	// DescendsFrom must return true for any tag returned by RecentTag for the
	// same revision.
	DescendsFrom(rev, tag string) (bool, error)
}

A Repo represents a code hosting source. Typical implementations include local version control repositories, remote version control servers, and code hosting sites.

A Repo must be safe for simultaneous use by multiple goroutines, and callers must not modify returned values, which may be cached and shared.

func LocalGitRepo

func LocalGitRepo(remote string) (Repo, error)

LocalGitRepo is like Repo but accepts both Git remote references and paths to repositories on the local file system.

func NewRepo

func NewRepo(vcs, remote string) (Repo, error)

type RevInfo

type RevInfo struct {
	Origin  *Origin
	Name    string    // complete ID in underlying repository
	Short   string    // shortened ID, for use in pseudo-version
	Version string    // version used in lookup
	Time    time.Time // commit time
	Tags    []string  // known tags for commit
}

A RevInfo describes a single revision in a source code repository.

type RunError

type RunError struct {
	Cmd      string
	Err      error
	Stderr   []byte
	HelpText string
}

func (*RunError) Error

func (e *RunError) Error() string

type Tag

type Tag struct {
	Name string
	Hash string // content hash identifying tag's content, if available
}

A Tag describes a single tag in a code repository.

type Tags

type Tags struct {
	Origin *Origin
	List   []Tag
}

A Tags describes the available tags in a code repository.

type UnknownRevisionError

type UnknownRevisionError struct {
	Rev string
}

UnknownRevisionError is an error equivalent to fs.ErrNotExist, but for a revision rather than a file.

func (*UnknownRevisionError) Error

func (e *UnknownRevisionError) Error() string

func (UnknownRevisionError) Is

func (UnknownRevisionError) Is(err error) bool

type VCSError

type VCSError struct {
	Err error
}

A VCSError indicates an error using a version control system. The implication of a VCSError is that we know definitively where to get the code, but we can't access it due to the error. The caller should report this error instead of continuing to probe other possible module paths.

TODO(golang.org/issue/31730): See if we can invert this. (Return a distinguished error for “repo not found” and treat everything else as terminal.)

func (*VCSError) Error

func (e *VCSError) Error() string

func (*VCSError) Unwrap

func (e *VCSError) Unwrap() error