gerrit

Documentation

Overview

Package gerrit contains Gerrit utility functions.

Index

• Constants
• Variables
• func EquivalentPatchsetRange(info *gerritpb.ChangeInfo) (minEquiPatchset, currentPatchset int, err error)
• func Tag(name string, suffix string) string
• func TruncateMessage(msg string) string
• func UnhandledError(ctx context.Context, err error, format string, args ...any) error
• type Client
• type Factory
  • func CachingFactory(lruSize int, f Factory) Factory
  • func InstrumentedFactory(f Factory) Factory
  • func NewFactory(ctx context.Context, mirrorHostPrefixes ...string) (Factory, error)
  • func TimeLimitedFactory(f Factory) Factory
• type MirrorIterator
  • func (it *MirrorIterator) Empty() bool
  • func (it *MirrorIterator) Next() grpc.CallOption
  • func (it *MirrorIterator) RetryIfStale(f func(opt grpc.CallOption) error) error
• type Whom
  • func (Whom) Descriptor() protoreflect.EnumDescriptor
  • func (x Whom) Enum() *Whom
  • func (Whom) EnumDescriptor() ([]byte, []int)
  • func (x Whom) Number() protoreflect.EnumNumber
  • func (x Whom) String() string
  • func (Whom) Type() protoreflect.EnumType
• type Whoms
  • func (whoms Whoms) Dedupe()
  • func (whoms Whoms) ToAccountIDsSorted(ci *gerritpb.ChangeInfo) []int64

Constants

const MaxMessageLength = 16384

MaxMessageLength is the max message length for Gerrit as of Jun 2020 based on error messages.

const PlaceHolder = "\n...[truncated too long message]"

PlaceHolder is added to the message when the length of the message exceeds `MaxMessageLength` and human message gets truncated.

Variables

var (
	Whom_name = map[int32]string{
		0: "NONE",
		1: "OWNER",
		2: "REVIEWERS",
		3: "CQ_VOTERS",
		4: "PS_UPLOADER",
	}
	Whom_value = map[string]int32{
		"NONE":        0,
		"OWNER":       1,
		"REVIEWERS":   2,
		"CQ_VOTERS":   3,
		"PS_UPLOADER": 4,
	}
)

Enum value maps for Whom.

var ErrGerritDeadlineExceeded = errors.New("Gerrit took too long to respond", transient.Tag)

var ErrOutOfQuota = errors.New("out of Gerrit Quota", transient.Tag)

var ErrStaleData = errors.New("fetched stale Gerrit data", transient.Tag)

var File_go_chromium_org_luci_cv_internal_gerrit_storage_proto protoreflect.FileDescriptor

Functions

func EquivalentPatchsetRange

func EquivalentPatchsetRange(info *gerritpb.ChangeInfo) (minEquiPatchset, currentPatchset int, err error)

EquivalentPatchsetRange computes range of patchsets code-wise equivalent to the current patchset.

Gerrit categorises each new patchset (aka Revision) according to difference from prior one. The rebases are counted as equivalent, even though dependencies may have changed. Thus, only REWORK changes code.

Generally, all patchsets are numbered 1,2,3,...n without gaps. But this function doesn't assume this, thus Gerrit might potentially support wiping out individual patchsets, creating gaps without affecting CV.

func Tag

func Tag(name string, suffix string) string

Tag constructs a CV specific Gerrit Tag for SetReview request.

See: https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#review-input Panics if name is not provided or name contains "~". suffix is optional.

func TruncateMessage

func TruncateMessage(msg string) string

TruncateMessage truncates the message and appends `PlaceHolder` so that the string doesn't exceed `MaxMessageLength`.

If the input message is a valid utf-8 string, the result string will also be a valid utf-8 string

func UnhandledError

func UnhandledError(ctx context.Context, err error, format string, args ...any) error

UnhandledError is used to process and annotate Gerrit errors.

Types

type Client

type Client interface {
	// Lists changes that match a query.
	//
	// Note, although the Gerrit API supports multiple queries, for which
	// it can return multiple lists of changes, this is not a foreseen use-case
	// so this API just includes one query with one returned list of changes.
	//
	// https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes
	ListChanges(ctx context.Context, in *gerritpb.ListChangesRequest, opts ...grpc.CallOption) (*gerritpb.ListChangesResponse, error)

	// Loads a change by id.
	//
	// https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#get-change
	GetChange(ctx context.Context, in *gerritpb.GetChangeRequest, opts ...grpc.CallOption) (*gerritpb.ChangeInfo, error)

	// Retrieves related changes of a revision.
	//
	// Related changes are changes that either depend on, or are dependencies of
	// the revision.
	//
	// https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#get-related-changes
	GetRelatedChanges(ctx context.Context, in *gerritpb.GetRelatedChangesRequest, opts ...grpc.CallOption) (*gerritpb.GetRelatedChangesResponse, error)

	// Lists the files that were modified, added or deleted in a revision.
	//
	// https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-files
	ListFiles(ctx context.Context, in *gerritpb.ListFilesRequest, opts ...grpc.CallOption) (*gerritpb.ListFilesResponse, error)

	// Set various review bits on a change.
	//
	// https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#set-review
	SetReview(ctx context.Context, in *gerritpb.SetReviewRequest, opts ...grpc.CallOption) (*gerritpb.ReviewResult, error)

	// Submit a specific revision of a change.
	//
	// https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#submit-revision
	SubmitRevision(ctx context.Context, in *gerritpb.SubmitRevisionRequest, opts ...grpc.CallOption) (*gerritpb.SubmitInfo, error)

	// Returns the email addresses linked in the given Gerrit account.
	//
	// https://gerrit-review.googlesource.com/Documentation/rest-api-accounts.html#list-account-emails
	ListAccountEmails(ctx context.Context, req *gerritpb.ListAccountEmailsRequest, opts ...grpc.CallOption) (*gerritpb.ListAccountEmailsResponse, error)
}

Client defines a subset of Gerrit API used by CV.

type Factory

type Factory interface {
	MakeClient(ctx context.Context, gerritHost, luciProject string) (Client, error)
	MakeMirrorIterator(ctx context.Context) *MirrorIterator
}

Factory creates Client tied to Gerrit host and LUCI project.

Gerrit host and LUCI project determine the authentication being used.

func CachingFactory

func CachingFactory(lruSize int, f Factory) Factory

CachingFactory caches clients produced by another Factory.

func InstrumentedFactory

func InstrumentedFactory(f Factory) Factory

InstrumentedFactory instruments RPCs.

func NewFactory

func NewFactory(ctx context.Context, mirrorHostPrefixes ...string) (Factory, error)

NewFactory returns Factory for use in production.

func TimeLimitedFactory

func TimeLimitedFactory(f Factory) Factory

TimeLimitedFactory limits duration per each kind of Gerrit RPC.

type MirrorIterator

type MirrorIterator []string

MirrorIterator starts with the Gerrit host as is and then iterates over mirrors.

Fail-safe: if all mirrors have been used, uses the host as is. However, users should use Empty() to detect this and if necessary should construct a new MirrorIterator.

Not goroutine-safe.

func (*MirrorIterator) Empty

func (it *MirrorIterator) Empty() bool

Empty returns true if MirrorIterator has already iterated over all the mirrors.

func (*MirrorIterator) Next

func (it *MirrorIterator) Next() grpc.CallOption

Next returns a grpc.CallOption.

func (*MirrorIterator) RetryIfStale

func (it *MirrorIterator) RetryIfStale(f func(opt grpc.CallOption) error) error

RetryIfStale retries the given function so long as it returns ErrStaleData and there is not yet tried mirror.

Executes the given function at least once. If there are no mirrors, defaults to virtual gerrit host.

Provides the given function with the grpc.CallOption which should be passed to the respective Client RPC call.

Returns whatever error the given function returned last.

type Whom

type Whom int32

Whom identifies one or a group of Gerrit users involved in the code review workflow.

const (
	Whom_NONE Whom = 0
	// CL owner.
	Whom_OWNER Whom = 1
	// CL Reviewers
	Whom_REVIEWERS Whom = 2
	// Who have voted on the CQ label.
	Whom_CQ_VOTERS Whom = 3
	// Uploader of the patchset that triggered a "New Patchset" Run.
	Whom_PS_UPLOADER Whom = 4
)

func (Whom) Descriptor

func (Whom) Descriptor() protoreflect.EnumDescriptor

func (Whom) Enum

func (x Whom) Enum() *Whom

func (Whom) EnumDescriptor

func (Whom) EnumDescriptor() ([]byte, []int)

Deprecated: Use Whom.Descriptor instead.

func (Whom) Number

func (x Whom) Number() protoreflect.EnumNumber

func (Whom) String

func (x Whom) String() string

func (Whom) Type

func (Whom) Type() protoreflect.EnumType

type Whoms

type Whoms []Whom

Whoms is a collection of `Whom`s.

func (Whoms) Dedupe

func (whoms Whoms) Dedupe()

Dedupe removes duplicates and sorts the whoms in-place.

func (Whoms) ToAccountIDsSorted

func (whoms Whoms) ToAccountIDsSorted(ci *gerritpb.ChangeInfo) []int64

ToAccountIDsSorted translates whom to actual Gerrit account ids in a CL.