README
¶
SourceControl
Vendor-agnostic interface through which Stovepipe talks to a version control system. It is the sole owner of URI semantics: a URI is an opaque, VCS-agnostic locator of a commit. The git:// scheme used by the reference backend is just one encoding — a Mercurial or Perforce backend mints its own behind the same contract. Nothing outside an implementation parses a URI; it is a token you hand back to ask questions about a ref.
A SourceControl is bound to a single queue (a repo+ref) when its Factory constructs it from a Config, so the behavioral methods take no queue argument. Per the repository's extension rules, this package holds the SourceControl interface, its Config, and the Factory interface only — concrete Factory implementations and the per-queue routing that picks a backend for a Config.QueueName live in the wiring layer.
Behavior
- Latest resolves the queue's ref to the URI of its latest commit — the commit a new validation
Requestis minted against duringingest. - IsAncestor answers whether one URI is an ancestor of another. The
processstage uses it to choose a build strategy: if the queue's last-green URI is no longer an ancestor of the latest commit, history was rewritten and a full build is required rather than an incremental one. - History returns a bounded, newest-first page of commit URIs on the ref, using the shared generic
page.Page[string](platform/base/page). It is paginated with an opaque cursor: callers pass an empty cursor for the newest page and the page'sNextCursorto walk further back, stopping when it is empty. Pagination keeps a remote backend cheap; callers join the URIs against the request store to render the greenness of each commit.
Errors
Implementations return plain errors and use the package sentinel ErrNotFound (with the IsNotFound / WrapNotFound helpers) when a queue, ref, or URI cannot be resolved. They do not classify errors as user- or infra-caused — the calling controller does that.
Implementations
- fake — an in-memory backend seeded with a queue's ref history (newest first), for examples and tests.
To add a backend, create sourcecontrol/{backend}/, implement the SourceControl interface, and return it from a New(...) constructor.
Documentation
¶
Overview ¶
Package sourcecontrol defines the contract through which Stovepipe talks to a version control system. It is the sole owner of URI semantics: a URI is an opaque, VCS-agnostic locator of a commit (e.g. "git://remote/repo/ref/.../<sha>" for the reference git backend, but a Mercurial or Perforce backend would mint its own scheme). Nothing outside an implementation parses a URI — it is a token handed back to ask questions ("what is the latest commit of this ref?", "is A an ancestor of B?"). A SourceControl is bound to a single queue (a repo+ref) at construction by its Factory, so its methods take no queue argument.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("source control reference not found")
ErrNotFound is returned when a queue, ref, or URI cannot be resolved by the implementation (for example an unknown queue, or an ancestry query referencing a URI that is not on the ref).
Functions ¶
func IsNotFound ¶
IsNotFound returns true if any error in the error chain is an ErrNotFound.
func WrapNotFound ¶
WrapNotFound wraps ErrNotFound with the original error from the implementation.
Types ¶
type Config ¶
type Config struct {
// QueueName identifies the queue (a repo+ref) this SourceControl serves.
QueueName string
}
Config carries the per-queue identity handed to a Factory. The system knows only the queue name; everything an implementation needs (the VCS endpoint, credentials, the ref it maps to) is injected at construction by the integrator.
type Factory ¶
type Factory interface {
// For returns the SourceControl for the given queue.
For(cfg Config) (SourceControl, error)
}
Factory builds the SourceControl for a queue. Implementations are provided by integrators (and tests) and inject whatever they need at construction. The per-queue routing adapter lives in the wiring layer, not here.
type SourceControl ¶
type SourceControl interface {
// Latest returns the URI of the latest commit on the queue's ref — the
// commit a new validation Request is minted against. Returns ErrNotFound if
// the queue or ref cannot be resolved.
Latest(ctx context.Context) (string, error)
// IsAncestor reports whether ancestor is an ancestor of descendant in the
// queue's history. Stovepipe uses it to decide the build strategy: when the
// last-green URI is no longer an ancestor of the latest commit (false),
// history was rewritten and a full build is required instead of an
// incremental one. Returns ErrNotFound if either URI is unknown to the ref.
IsAncestor(ctx context.Context, ancestor, descendant string) (bool, error)
// History returns a bounded page of the queue's commit URIs, newest first.
// It is paginated with an opaque cursor so a remote backend stays cheap:
// callers pass an empty cursor for the first (newest) page and the page's
// NextCursor to walk further back, stopping when NextCursor is empty. limit
// caps the page size; a limit of zero or less lets the implementation choose a
// default. Callers join the returned URIs against the request store to render
// the greenness/status of each commit. Returns ErrNotFound if the cursor does
// not refer to a position on the ref.
History(ctx context.Context, cursor string, limit int) (page.Page[string], error)
}
SourceControl resolves and compares commit URIs for the single queue it is bound to. Implementations interpret URIs; callers treat them as opaque tokens.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fake provides an in-memory sourcecontrol.SourceControl seeded with a single queue's linear ref history, ordered newest-first.
|
Package fake provides an in-memory sourcecontrol.SourceControl seeded with a single queue's linear ref history, ordered newest-first. |
|
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |