sourcedriver

Documentation

Overview

Package sourcedriver defines the API used to implement source drivers.

A source driver provides the provider-specific implementation that a source uses to communicate with the service that provides the repositories.

Index

• type Cloner
• type Config
• type ConfigContext
• type ConfigLoader
• type ImplicitSource
• type InitParameters
• type Registration
• type RemoteRepo
• type Source

Types

type Cloner

type Cloner interface {
	// Clone makes a local clone of the remote repository in the given
	// directory.
	Clone(
		ctx context.Context,
		dir string,
		log logs.Log,
	) error
}

Cloner is an interface for cloning a specific remote repository.

Cloners are obtained via the Cloner() method on a Source.

type Config

type Config interface {
	// NewSource constructs a new source from this configuration.
	NewSource() Source

	// DescribeSourceConfig returns a human-readable description of the
	// configuration.
	DescribeSourceConfig() string
}

Config is an interface for driver-specific configuration options for a repository source.

The underlying implementation must not be used by more than one driver.

type ConfigContext

type ConfigContext interface {
	// EvalContext returns the HCL evaluation context to be used when to
	// decoding HCL content.
	EvalContext() *hcl.EvalContext

	// NormalizePath resolves a (potentially relative) filesystem path to an
	// absolute path.
	//
	// If *p begins with a tilde (~), it is resolved relative to the user's home
	// directory.
	//
	// If *p is a relative path, it is resolved to an absolute path relative to
	// the directory containing the configuration file that is currently being
	// parsed.
	//
	// It does nothing if p is nil or *p is empty.
	NormalizePath(p *string) error

	// UnmarshalVCSConfig stores the configuration for a VCS driver in the value
	// pointed to by v.
	//
	// It panics v is nil or not a pointer.
	//
	// driver is the name (not the alias) of the VCS driver that provides the
	// configuration, as specified in its vcsdriver.Registration entry.
	//
	// Multiple drivers may share the same name by using different aliases. In
	// this case, the type of the value pointed to by v the driver that supplies
	// a config of the type pointed to by v is used.
	UnmarshalVCSConfig(driver string, v interface{}) error
}

ConfigContext provides operations used when loading source configuration.

type ConfigLoader

type ConfigLoader interface {
	// Unmarshal unmarshals the contents of a "source" block.
	Unmarshal(ctx ConfigContext, b hcl.Body) (Config, error)

	// ImplicitSources returns the configuration to use for "implicit" sources
	// provided by this driver without explicit configuration.
	ImplicitSources(ctx ConfigContext) ([]ImplicitSource, error)
}

ConfigLoader is an interface for loading driver-specific source configuration.

type ImplicitSource

type ImplicitSource struct {
	// Name is the unique name for the source.
	//
	// If the user defines an explicit source with the same name, this implicit
	// source is ignored.
	Name string

	// Config is the configuration of this source.
	Config Config
}

ImplicitSource represents a source that is provided by this driver without explicit configuration.

type InitParameters

type InitParameters struct {
	BaseURL *url.URL
}

InitParameters are the parameters passed to the Init() method of a Source.

type Registration

type Registration struct {
	// Name is the (preferred) name of the driver, as referenced within
	// configuration files.
	Name string

	// Description is a short human-readable description of the driver.
	Description string

	// ConfigLoader loads configuration for this driver.
	ConfigLoader ConfigLoader
}

Registration encapsulates the information required to register a source driver implementation with Grit.

type RemoteRepo

type RemoteRepo struct {
	// ID uniquely identifies the repository within the source.
	ID string

	// Name is the human-readable name of the repository.
	//
	// The formatting and uniqueness guarantees of the repository name are
	// driver-specific.
	Name string

	// Description is a human-readable description of the repository.
	Description string

	// WebURL is the URL of the repository's web page, if available.
	//
	// This is a page viewable in a browser by a human, not the URL used to
	// clone the repository.
	WebURL string

	// RelativeCloneDir is the directory into which a local clone of this
	// repository is placed, relative to the source's clone directory.
	//
	// It uses the path separator native to the current OS.
	RelativeCloneDir string
}

RemoteRepo is a reference to a remote repository provided by a source.

type Source

type Source interface {
	http.Handler

	// Init initializes the source.
	//
	// It is called before the daemon starts serving API requests. If an error
	// is returned, the daemon is stopped.
	Init(ctx context.Context, p InitParameters, log logs.Log) error

	// Run performs any background processing required by the source.
	//
	// It is called in its own goroutine after the source is initialized. It
	// should run until ctx is canceled or there is nothing left to do. The
	// context is canceled when the daemon shuts down.
	//
	// If it returns an error before ctx is canceled, the daemon is stopped.
	Run(ctx context.Context, log logs.Log) error

	// Status returns a brief description of the current state of the source.
	//
	// This may include information about connectivity with a remote server,
	// authenticated details, etc.
	Status(ctx context.Context, log logs.Log) (string, error)

	// SignIn signs in to the source.
	SignIn(ctx context.Context, log logs.Log) error

	// SignOut signs out of the source.
	SignOut(ctx context.Context, log logs.Log) error

	// Resolve resolves a repository name, URL, or other identifier to a set of
	// possible repositories.
	//
	// The details of the resolution logic is implementation defined.
	// Implementations should be as generous as possible in what they accept but
	// should avoid returning repositories that only partially match the input.
	// Multiple repositories may be returned to indicate that the query is
	// ambiguous.
	//
	// The query string is typically captured directly from user input and has
	// not been sanitized. The implementation must not return an error if the
	// query is invalid; instead return an empty slice.
	Resolve(ctx context.Context, query string, log logs.Log) ([]RemoteRepo, error)

	// Cloner returns a cloner that clones the repository with the given ID,
	// and information about the repository being cloned.
	//
	// id is the repository ID, as discovered by a prior call to Resolve().
	Cloner(ctx context.Context, id string, log logs.Log) (Cloner, RemoteRepo, error)

	// Suggest returns a set of repositories that have names related to the
	// given word (which may be empty).
	Suggest(word string, log logs.Log) map[string][]RemoteRepo
}

Source is an interface for a source provided by this driver.