Documentation
¶
Overview ¶
Package source defines the read-only Source interface implemented by every VCS backend (GitHub, GHES, GitLab, ...). It only enumerates repos and yields what's needed to clone and dump them, no method mutates the upstream VCS.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrTransient = errors.New("transient failure")
ErrTransient marks a failure that is likely to pass: a rate limit that could not be waited out, or a server error that outlasted its retries.
The pipeline fetches metadata before it writes anything, and stops a repository whose metadata failed this way with nothing stored, because the next run will probably get through. Any other failure, a missing permission say, would fail every run the same way, so the repository's code is stored regardless and only then is the repository failed. A source that marks nothing gets the second behaviour for every failure, which is the safe one.
Functions ¶
func KeepTLS ¶ added in v0.1.24
func KeepTLS(next http.RoundTripper) http.RoundTripper
KeepTLS returns next with one rule added: a redirect from an https URL to one that is not https fails before anything is sent. Without it a redirect to plain http sends the request, and any credential on it, in the clear, and reads an answer anyone on the way could have written.
func ScrubRedirect ¶ added in v0.1.24
ScrubRedirect returns err, or, when err is a redirect a source refused, the refusal alone. Go's client wraps a transport's error in a url.Error quoting the URL it was for, path and query string included, and for a refused hop that URL is the one the redirect chose. A source passes every error from its API client through this before it adds its own words.
func StayOnAPI ¶ added in v0.1.24
func StayOnAPI(api *url.URL, next http.RoundTripper) http.RoundTripper
StayOnAPI returns next with the other rule: a hop of a redirect to anything but the scheme and host of api fails before anything is sent. None of the endpoints a source calls redirects off its API. A redirect that does is the API's server, or something in front of it, pointing somewhere gitdr has no reason to trust, and the answer from there would be read as the API's: a list of repositories whose clone URLs name that host, where git then sends the token.
Scheme and host are compared exactly, port included, the way a source decides which requests carry its credential. A host spelled another way is another host, the safe way to be wrong, and an api with no host matches nothing.
Types ¶
type Filter ¶
type Filter struct {
Include []string // if non-empty, only repos matching one of these are kept
Exclude []string // repos matching any of these are dropped
}
Filter narrows which repositories a backup run targets. An empty Filter selects everything the credential can see. Include/Exclude are matched by the Source implementation (typically against "owner/name"); Exclude wins over Include.
type GitAuther ¶
type GitAuther interface {
// GitAuthHeader returns a full HTTP header line, e.g. "Authorization: Basic ...".
GitAuthHeader(ctx context.Context) (string, error)
}
GitAuther is an optional interface for Sources that authenticate git clones over HTTPS. The pipeline injects the returned header into git via env, never argv, so the token stays out of process listings. Sources without auth (e.g. local fixtures) simply don't implement it.
It is called once per git command, immediately before the command starts, so it must be cheap: a run over a large organisation calls it thousands of times. Asking each time is what lets a credential that changes during a run, a token file replaced or an App token renewed, reach the next command instead of the next run.
type RedirectError ¶ added in v0.1.24
type RedirectError struct {
From string // the scheme and host redirected from, or "" when the response does not say
To string // the scheme and host redirected to
Reason string
}
RedirectError is a redirect a source refused to follow. It names the two ends by scheme and host alone: where a redirect points is whoever sent it's to choose, and the rest of that URL, its query string above all, can carry anything, a credential included.
func (*RedirectError) Error ¶ added in v0.1.24
func (e *RedirectError) Error() string
type Repo ¶
type Repo struct {
Host string `json:"host"` // VCS host, e.g. "github.com"
Owner string `json:"owner"` // org or user that owns the repo
Name string `json:"name"` // repository name (no owner prefix)
CloneURL string `json:"cloneUrl"` // HTTPS clone URL; credentials are applied at clone time, never embedded here
DefaultBranch string `json:"defaultBranch"` // default branch name, if known
Archived bool `json:"archived"` // upstream archived flag
SizeKB int64 `json:"sizeKb"` // approximate size in KiB, if reported
}
Repo identifies a single repository discovered on a Source, plus the minimal attributes the pipeline needs to back it up.
type Source ¶
type Source interface {
// ListRepos enumerates repositories visible to the configured identity,
// applying the include/exclude filter.
ListRepos(ctx context.Context, f Filter) ([]Repo, error)
// CloneURL returns the URL to clone r over HTTPS. Authentication is supplied
// out of band at clone time (an injected Authorization header); the returned
// URL must not embed credentials.
CloneURL(ctx context.Context, r Repo) (string, error)
// FetchMetadata returns repository metadata as JSON bytes for archival. In the
// walking skeleton this is a minimal repo descriptor; the full per-resource dump
// (issues, PRs, releases, ...) is added later (M5).
FetchMetadata(ctx context.Context, r Repo) ([]byte, error)
}
Source is the read-only interface implemented by every VCS backend.
Invariant: a Source exposes no mutating operation. It can only read.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package github implements the read-only Source for GitHub.com (and, by base URL, GitHub Enterprise Server).
|
Package github implements the read-only Source for GitHub.com (and, by base URL, GitHub Enterprise Server). |
|
Package gitlab implements the read-only Source for GitLab.com and self-managed GitLab.
|
Package gitlab implements the read-only Source for GitLab.com and self-managed GitLab. |