blob: 4b123f33004648decce009f95b6cc92316a76ebe [file] [log] [blame]
package gitstore
import (
"context"
"time"
"go.skia.org/infra/go/vcsinfo"
)
const (
// ALL_BRANCHES is a placeholder which can be used to retrieve IndexCommits
// for every branch, as opposed to just one.
ALL_BRANCHES = "@all-commits"
// DELETE_BRANCH is a placeholder which can be used as a value in the
// branch map passed to GitStore.PutBranches to signify that the branch
// should be deleted.
DELETE_BRANCH = "@DELETE"
)
// GitStore defines the functions of a data store for Git metadata (aka vcsinfo.LongCommit)
// Each GitStore instance relates to one repository that is defined in the constructor of the
// implementation.
type GitStore interface {
// Put stores the given commits. They can be retrieved in order of timestamps by using
// RangeByTime or RangeN (no topological ordering). The Index and Branch information
// on the commits must be correct, or the results of RangeN and RangeByTime will not
// be correct.
Put(ctx context.Context, commits []*vcsinfo.LongCommit) error
// Get retrieves the commits identified by 'hashes'. The return value will always have the
// length of the input value and the results will line up by index. If a commit does not exist
// the corresponding entry in the result is nil.
// The function will only return an error if the retrieval operation (the I/O) fails, not
// if the given hashes do not exist or are invalid.
Get(ctx context.Context, hashes []string) ([]*vcsinfo.LongCommit, error)
// PutBranches updates the given branch heads in the GitStore. The 'branches' parameter
// maps branch name to commit hash to indicate the head of a branch. All of the referenced
// commits must already exist in the GitStore. If the DELETE_BRANCH string is used instead
// of a commit hash, then the branch is removed. Any existing branches which are not
// included in the call to PutBranches are left unchanged.
PutBranches(ctx context.Context, branches map[string]string) error
// GetBranches returns the current branches in the store. It maps[branchName]->BranchPointer.
// A BranchPointer contains the HEAD commit and also the Index of the HEAD commit, which is
// usually the total number of commits in the branch minus 1.
GetBranches(ctx context.Context) (map[string]*BranchPointer, error)
// RangeN returns all commits in the half open index range [startIndex, endIndex), thus not
// including endIndex. It returns the commits in the given branch sorted in ascending
// order by Index, which only includes commits on the first-parent ancestry chain, per the
// definition of vcsinfo.IndexCommit. This does not make sense for branch == ALL_BRANCHES,
// because different lines of history may use the same indexes. Therefore, the results of
// RangeN for ALL_BRANCHES may not be complete or correct.
RangeN(ctx context.Context, startIndex, endIndex int, branch string) ([]*vcsinfo.IndexCommit, error)
// RangeByTime returns all commits in the half open time range [start, end), thus not
// including commits at 'end' time. Set branch = ALL_BRANCHES to retrieve all commits
// for every branch within the specified range.
// Caveat: The returned results will match the requested range, but will be sorted by Index.
// So if the timestamps of the commits within a branch are not in order they will be
// unordered in the results. In the case of branch == ALL_BRANCHES, some indexes may be
// repeated, because different lines of history may use the same indexes.
RangeByTime(ctx context.Context, start, end time.Time, branch string) ([]*vcsinfo.IndexCommit, error)
}
// GitStoreBased is an interface that tags an object as being based on GitStore and the
// underlying GitStore instance can be retrieved. e.g.
//
// if gsb, ok := someInstance.(GitStoreBased); ok {
// gitStore := gsb.GetGitStore()
// ... do something with gitStore
// }
//
type GitStoreBased interface {
// GetGitStore returns the underlying GitStore instances.
GetGitStore() GitStore
}
// BranchPointer captures the HEAD of a branch and the index of that commit.
type BranchPointer struct {
Head string
Index int
}
// RepoInfo contains information about one repo in the GitStore.
type RepoInfo struct {
// Numeric id of the repo. This is unique within all repos in a BT table. This ID is uniquely
// assigned whenever a new repo is added.
ID int64
// RepoURL contains the URL of the repo as returned by git.NormalizeURL(...).
RepoURL string
// Branches contain all the branches in the repo, mapping branch_name -> branch_pointer.
Branches map[string]*BranchPointer
}