Documentation

Index

Constants

View Source
const (
	// MaxAutoCommitsPerDay indicates how many commits may be landed by the
	// findit service account in any 24 hour period.
	MaxAutoCommitsPerDay = 8
	// MaxAutoRevertsPerDay indicates how many reverts may be created by the
	// findit service account in any 24 hour period.
	MaxAutoRevertsPerDay = 20

	// MaxCulpritAge indicates the maximum delay allowed between a culprit
	// and findit reverting it.
	MaxCulpritAge = 24 * time.Hour

	// MaxRetriesPerCommit indicates how many times the auditor can retry
	// audting a commit if some rules return errors. This retry is meant to
	// handle transient errors on the underlying services.
	MaxRetriesPerCommit = 6 // Thirty minutes if checking every 5 minutes.
)
View Source
const (

	// GerritScope is a link of Gerrit authorization.
	GerritScope = "https://www.googleapis.com/auth/gerritcodereview"
	// EmailScope is a link of Google email authorization.
	EmailScope = "https://www.googleapis.com/auth/userinfo.email"
	// FailedBuildPrefix is a prefix that is followed by some failed builds in
	// commit messages.
	FailedBuildPrefix = "Sample Failed Build:"
	// FailedStepPrefix is a prefix that is followed by some failed steps in
	// commit messages.
	FailedStepPrefix = "Sample Failed Step:"
	// FlakyTestPrefix is a prefix that is followed by some flaky tests in
	// commit messages.
	FlakyTestPrefix = "Sample Flaky Test:"
)

Variables

This section is empty.

Functions

func GetAuthenticatedHTTPClient

func GetAuthenticatedHTTPClient(ctx context.Context, scopes ...string) (*http.Client, error)

GetAuthenticatedHTTPClient gets http clients from given scopes.

func GetToken

func GetToken(ctx context.Context, tokenName, packedTokens string) (string, bool)

GetToken returns the value of a token, and a boolean indicating if the token exists (as opposed to the token being the empty string).

func MustGitilesTime

func MustGitilesTime(v string) *google_protobuf.Timestamp

MustGitilesTime convert time string into golang protobuf timestamp.

func PostIssue

func PostIssue(ctx context.Context, cfg *RefConfig, s, o, d string, cs *Clients, components, labels []string) (int32, error)

PostIssue will create an issue based on the given parameters.

func ProdBuildbucketClientFactory

func ProdBuildbucketClientFactory(httpClient *http.Client) buildbucketpb.BuildsClient

ProdBuildbucketClientFactory is a BuildbucketClientFactory used to create production buildbucket PRPC clients.

func ProdGitilesClientFactory

func ProdGitilesClientFactory(host string, httpClient *http.Client) (gitilespb.GitilesClient, error)

ProdGitilesClientFactory is a GitilesClientFactory used to create production gitiles REST clients.

func SetToken

func SetToken(ctx context.Context, tokenName, tokenValue, packedTokens string) (string, error)

SetToken modifies the value of the token if it exists, or adds it if not.

Types

type AccountRules

type AccountRules struct {
	// Account is the account to filter on for account specific rules.
	Account      string
	Rules        []Rule
	Notification Notification
}

AccountRules is a rule that applies to a commit if the commit has a given account as either its author or its committer.

func AutoRollRules

func AutoRollRules(account string, files, dirs []string) AccountRules

AutoRollRules returns an AccountRules instance for an account which should only modify the given set of files and directories.

func (AccountRules) MatchesCommit

func (ar AccountRules) MatchesCommit(c *git.Commit) bool

MatchesCommit determines whether the AccountRules set it's bound to, applies to the given commit.

func (AccountRules) MatchesRelevantCommit

func (ar AccountRules) MatchesRelevantCommit(c *RelevantCommit) bool

MatchesRelevantCommit determines whether the AccountRules set it's bound to, applies to the given commit entity.

type AcknowledgeMerge

type AcknowledgeMerge struct {
	*cpb.AcknowledgeMerge
}

AcknowledgeMerge is a Rule that acknowledges any merge into a release branch.

func (AcknowledgeMerge) GetName

func (rule AcknowledgeMerge) GetName() string

GetName returns the name of the rule.

func (AcknowledgeMerge) Run

Run executes the rule.

type AuditParams

type AuditParams struct {
	TriggeringAccount string
	RepoCfg           *RefConfig
	RepoState         *RepoState
}

AuditParams exposes object shared by all rules (and the worker goroutines they are run on).

type AuditStatus

type AuditStatus int

AuditStatus is the enum for RelevantCommit.Status.

const (
	// AuditScheduled is the status when an audit is scheduled.
	AuditScheduled AuditStatus = iota
	// AuditCompleted is the status when an audit has been completed.
	AuditCompleted
	// AuditCompletedWithActionRequired is the status when an audit has
	// completed but requires some actions. e.g. notifications.
	AuditCompletedWithActionRequired
	// AuditFailed is the status when an audit has failed.
	AuditFailed
	// AuditPending is the status when some rules may not be decidable yet.
	AuditPending
)

func (AuditStatus) ColorCode

func (as AuditStatus) ColorCode() string

ColorCode returns a string used to color code the string, as a css class for example.

func (AuditStatus) ToShortString

func (as AuditStatus) ToShortString() string

ToShortString returns a short string version of this status meant to be used as datapoint labels for metrics.

func (AuditStatus) ToString

func (as AuditStatus) ToString() string

ToString returns a human-readable version of this status.

type AutoCommitsPerDay

type AutoCommitsPerDay struct {
	*cpb.AutoCommitsPerDay
}

AutoCommitsPerDay is a Rule that verifies that at most MaxAutoCommitsPerDay commits in the 24 hours preceding the triggering commit were committed by the triggering account.

func (AutoCommitsPerDay) GetName

func (rule AutoCommitsPerDay) GetName() string

GetName returns the name of the rule

func (AutoCommitsPerDay) Run

Run executes the rule.

type AutoRevertsPerDay

type AutoRevertsPerDay struct {
	*cpb.AutoRevertsPerDay
}

AutoRevertsPerDay is a Rule that verifies that at most MaxAutoRevertsPerDay commits in the 24 hours preceding the triggering commit were authored by the triggering account.

func (AutoRevertsPerDay) GetName

func (rule AutoRevertsPerDay) GetName() string

GetName returns the name of the rule

func (AutoRevertsPerDay) Run

Run executes the rule.

type BranchInfo

type BranchInfo struct {
	PdfiumBranch   string `json:"pdfium_branch"`
	SkiaBranch     string `json:"skia_branch"`
	WebrtcBranch   string `json:"webrtc_branch"`
	V8Branch       string `json:"v8_branch"`
	ChromiumBranch string `json:"chromium_branch"`
	Milestone      int    `json:"milestone"`
}

BranchInfo represents the main branch information of a specific Chrome release

type BuildbucketClientFactory

type BuildbucketClientFactory func(httpClient *http.Client) buildbucketpb.BuildsClient

BuildbucketClientFactory is function type for generating new Buildbucket clients, both the production client factory and any mock factories are expected to implement it.

type ChangeReviewed

type ChangeReviewed struct {
	*cpb.ChangeReviewed
}

ChangeReviewed is a RuleFunc that verifies that someone other than the owner has reviewed the change.

func (ChangeReviewed) GetName

func (r ChangeReviewed) GetName() string

GetName returns the name of the rule.

func (ChangeReviewed) Run

Run executes the rule.

type Clients

type Clients struct {

	// This is already an interface so we use it as exported.
	Monorail       monorail.MonorailClient
	GitilesFactory GitilesClientFactory
	// contains filtered or unexported fields
}

Clients exposes clients for external services shared throughout one request.

func InitializeClients

func InitializeClients(ctx context.Context, cfg *RefConfig, client *http.Client) (*Clients, error)

InitializeClients returns clients that connects to given repositories.

func (*Clients) ConnectAll

func (c *Clients) ConnectAll(ctx context.Context, cfg *RefConfig, client *http.Client) error

ConnectAll creates the clients so the rules can use them, also sets necessary values in the context for the clients to talk to production.

func (*Clients) NewBuildbucketClient

func (c *Clients) NewBuildbucketClient() buildbucketpb.BuildsClient

NewBuildbucketClient uses a factory set in the Clients object and its httpClient to create a new buildbucket client.

func (*Clients) NewGitilesClient

func (c *Clients) NewGitilesClient(host string) (gitilespb.GitilesClient, error)

NewGitilesClient uses a factory set in the Clients object and its httpClient to create a new gitiles client.

type CommentOnBugToAcknowledgeMerge

type CommentOnBugToAcknowledgeMerge struct {
	*cpb.CommentOnBugToAcknowledgeMerge
}

CommentOnBugToAcknowledgeMerge is used as the notification function of merge-ack-rule.

func (CommentOnBugToAcknowledgeMerge) Notify

Notify implements Notification.

type CommentOrFileMonorailIssue

type CommentOrFileMonorailIssue struct {
	*cpb.CommentOrFileMonorailIssue
}

CommentOrFileMonorailIssue files a bug to Monorail.

It checks if the failure has already been reported to Monorail and files a new bug if it hasn't. If a bug already exists this function will try to add a comment and associate it to the bug.

func (CommentOrFileMonorailIssue) Notify

Notify implements Notification.

type CulpritAge

type CulpritAge struct {
	*cpb.CulpritAge
}

CulpritAge is a Rule that verifies that the culprit being reverted is less than 24 hours older than the revert.

func (CulpritAge) GetName

func (rule CulpritAge) GetName() string

GetName returns the name of the rule

func (CulpritAge) Run

func (rule CulpritAge) Run(ctx context.Context, ap *AuditParams, rc *RelevantCommit, cs *Clients) (*RuleResult, error)

Run executes the rule.

type CulpritInBuild

type CulpritInBuild struct {
	*cpb.CulpritInBuild
}

CulpritInBuild is a Rule that verifies that the culprit is included in the list of changes of the failed build.

func (CulpritInBuild) GetName

func (rule CulpritInBuild) GetName() string

GetName returns the name of the rule

func (CulpritInBuild) Run

Run executes the rule.

type DummyRule

type DummyRule struct {
	Name   string
	Result *RuleResult
}

DummyRule is a rule that always returns the value of the result field when run.

func (DummyRule) GetName

func (rule DummyRule) GetName() string

GetName returns the name of the rule.

func (DummyRule) Run

func (rule DummyRule) Run(c context.Context, ap *AuditParams, rc *RelevantCommit, cs *Clients) (*RuleResult, error)

Run returns the result struct field.

type DynamicRefFunc

type DynamicRefFunc func(context.Context, RefConfig) ([]*RefConfig, error)

DynamicRefFunc is a functype for functions that match a RefConfig with a dynamically determined ref.

It is expected to receive the generic RefConfig as hardcoded in ruleMap, passed by value to prevent the implementation from modifying it. It is expected to return a slice of references to RefConfigs, where each matches a ref to audit, and its values BranchName and Metadata have been modified accordingly.

Note that for changes to any other field of RefConfig made by functions implementing this interface to persist and apply to audits, the Scheduler needs to be modified to save them to the RepoState, and the SetConcreteRef function below needs to be modified to set them in the copy of RefConfig to be passed to the scan/audit/notify functions.

type FailedBuildIsAppropriateFailure

type FailedBuildIsAppropriateFailure struct {
	*cpb.FailedBuildIsAppropriateFailure
}

FailedBuildIsAppropriateFailure is a Rule that verifies that the referred build contains a failed step appropriately named.

func (FailedBuildIsAppropriateFailure) GetName

func (rule FailedBuildIsAppropriateFailure) GetName() string

GetName returns the name of the rule

func (FailedBuildIsAppropriateFailure) Run

Run executes the rule.

type FileBugForMergeApprovalViolation

type FileBugForMergeApprovalViolation struct {
	*cpb.FileBugForMergeApprovalViolation
}

FileBugForMergeApprovalViolation is the notification function for merge-approval-rules.

func (FileBugForMergeApprovalViolation) Notify

Notify implements Notification.

type GitilesClientFactory

type GitilesClientFactory func(host string, httpClient *http.Client) (gitilespb.GitilesClient, error)

GitilesClientFactory is function type for generating new gitiles clients, both the production client factory and any mock factories are expected to implement it.

type MockMonorailClient

type MockMonorailClient struct {
	Il *mr.IssuesListResponse
	Cl *mr.ListCommentsResponse
	Ic *mr.InsertCommentResponse
	Ii *mr.InsertIssueResponse
	Gi *mr.Issue
	E  error
}

MockMonorailClient is a mock monorail client that used for testing.

func (MockMonorailClient) GetIssue

func (c MockMonorailClient) GetIssue(ctx context.Context, in *mr.GetIssueRequest, opts ...grpc.CallOption) (*mr.Issue, error)

GetIssue pretends to get an issue by id.

func (MockMonorailClient) InsertComment

InsertComment pretends to post comments to an issue.

func (MockMonorailClient) InsertIssue

InsertIssue pretends to create an issue.

func (MockMonorailClient) IssuesList

IssuesList pretends to list issues from a project.

func (MockMonorailClient) ListComments

ListComments pretends to return comments of an issue.

type Notification

type Notification interface {
	Notify(ctx context.Context, cfg *RefConfig, rc *RelevantCommit, cs *Clients, state string) (string, error)
}

Notification is a type that needs to be implemented by functions intended to notify about violations in rules.

The notification function is expected to determine if there is a violation by checking the results of calling .GetViolations() on the RelevantCommit and not just blindly send a notification.

The state parameter is expected to be used to keep the state between retries to avoid duplicating notifications, its value will be either the empty string or the first element of the return value of a previous call to this function for the same commit.

e.g. Return ('notificationSent', nil) if everything goes well, and if the incoming state already equals 'notificationSent', then don't send the notification, as that would indicate that a previous call already took care of that. The state string is a short freeform string that only needs to be understood by the NotificationFunc itself, and should exclude colons (`:`).

type OnlyCommitsOwnChange

type OnlyCommitsOwnChange struct {
	*cpb.OnlyCommitsOwnChange
}

OnlyCommitsOwnChange is a Rule that verifies that commits landed by the service account were also authored by that service account.

func (OnlyCommitsOwnChange) GetName

func (rule OnlyCommitsOwnChange) GetName() string

GetName returns the name of the rule

func (OnlyCommitsOwnChange) Run

Run executes the rule.

type OnlyMergeApprovedChange

type OnlyMergeApprovedChange struct {
	*cpb.OnlyMergeApprovedChange
}

OnlyMergeApprovedChange is a Rule that verifies that only approved changes are merged into a release branch.

func (OnlyMergeApprovedChange) GetName

func (r OnlyMergeApprovedChange) GetName() string

GetName returns the name of the rule.

func (OnlyMergeApprovedChange) Run

Run executes the rule.

type OnlyModifiesFilesAndDirsRule

type OnlyModifiesFilesAndDirsRule struct {
	*cpb.OnlyModifiesFilesAndDirsRule
}

OnlyModifiesFilesAndDirsRule is a shared implementation for Rules which verify that only the given files and directories are modified by the audited CL.

func (OnlyModifiesFilesAndDirsRule) GetName

func (rule OnlyModifiesFilesAndDirsRule) GetName() string

GetName returns the name of the rule, from the struct field 'Name'.

func (OnlyModifiesFilesAndDirsRule) Run

Run executes the rule as configured by the struct fields 'Files' and 'Dirs'.

type Path

type Path struct {
	Name string
	Type string
}

Path is a struct describing a file or directory within the git repo.

type RefConfig

type RefConfig struct {
	BaseRepoURL     string
	GerritURL       string
	BranchName      string
	Metadata        string
	StartingCommit  string
	MonorailAPIURL  string // Only intended for release branches
	MonorailProject string
	// Do not use "AuditFailure" as a key in this map, it may cause a clash
	// with the notification state for failed audits.
	Rules              map[string]AccountRules
	NotifierEmail      string
	DynamicRefFunction DynamicRefFunc
	// OverwriteLastKnownCommit is used for unpausing a ref. Oncall should
	// modify this configuration to help resume the scanning.
	OverwriteLastKnownCommit string
}

RefConfig represents the hard-coded config for a monitored repo and a pointer to the entity representing its datastore-persisted state.

func GetReleaseConfig

func GetReleaseConfig(ctx context.Context, cfg RefConfig, branchRefsURLContents []string, branchInfos []BranchInfo) ([]*RefConfig, error)

GetReleaseConfig is a helper function to get the ref and milestone dynamically.

func ReleaseConfig

func ReleaseConfig(ctx context.Context, cfg RefConfig) ([]*RefConfig, error)

ReleaseConfig is the skeleton of a function to get the ref and milestone dynamically.

func (*RefConfig) LinkToCommit

func (rc *RefConfig) LinkToCommit(commit string) string

LinkToCommit composes a url to a specific commit

func (*RefConfig) RepoURL

func (rc *RefConfig) RepoURL() string

RepoURL composes the url of the repository by appending the branch.

func (*RefConfig) SetConcreteRef

func (rc *RefConfig) SetConcreteRef(ctx context.Context, rs *RepoState) *RefConfig

SetConcreteRef returns a copy of the repoconfig modified to account for dynamic refs.

type RelevantCommit

type RelevantCommit struct {
	RepoStateKey *ds.Key `gae:"$parent"`
	CommitHash   string  `gae:"$id"`

	PreviousRelevantCommit string
	Status                 AuditStatus
	Result                 []RuleResult
	CommitTime             time.Time
	CommitterAccount       string
	AuthorAccount          string
	CommitMessage          string `gae:",noindex"`
	Retries                int32

	// This will catch deprecated fields such as IssueID
	LegacyFields ds.PropertyMap `gae:",extra"`

	// NotifiedAll will be true if all applicable notifications have been
	// processed.
	NotifiedAll bool

	// NotificationStates will have strings of the form `key:value` where
	// the key identifies a specific ruleset that might apply to this
	// commit and value is a freeform string that makes sense to the
	// notification function, used to keep track of the state between
	// retries. e.g. To avoid sending duplicate emails if the notification
	// sends multiple emails and only partially succeeds on the first
	// attempt.
	NotificationStates []string

	// LastExternalPoll records when the commit was last attempted
	// to be audited. This is useful for audit rules that can be left
	// undecided for a period of time, such as TBR auditing in order to
	// limit the frequency of polling external systems.
	LastExternalPoll time.Time
}

RelevantCommit points to a node in a linked list of commits that have been considered relevant by CommitScanner.

func (*RelevantCommit) GetNotificationState

func (rc *RelevantCommit) GetNotificationState(ruleSetName string) string

GetNotificationState retrieves the state for a rule set from the NotificationStates field.

func (*RelevantCommit) GetViolations

func (rc *RelevantCommit) GetViolations() []RuleResult

GetViolations returns the subset of RuleResults that are violations.

func (*RelevantCommit) SetNotificationState

func (rc *RelevantCommit) SetNotificationState(ruleSetName string, state string)

SetNotificationState stores the state for a given rule set.

func (*RelevantCommit) SetResult

func (rc *RelevantCommit) SetResult(rr RuleResult) bool

SetResult appends the given RuleResult to the array of results for this commit, or update it if one with the same RuleName is already present. Returns a boolean indicating whether a change was performed.

type RepoState

type RepoState struct {
	// RepoURL is expected to point to a branch e.g.
	// https://chromium.googlesource.com/chromium/src.git/+/master
	RepoURL string `gae:"$id"`

	LastKnownCommit        string
	LastKnownCommitTime    time.Time
	LastRelevantCommit     string
	LastRelevantCommitTime time.Time

	// LastUpdatedTime is the wall clock time when the last scan was
	// successful.
	LastUpdatedTime time.Time

	// Paused indicates whether this ref paused begin audited. This pausing
	// could be caused by: 1) A non-fast-forward update makes LastKnownCommit
	// become an unaccessible commit; 2) Gitiles git.Log API returns too many
	// commits or encounters some errors, which causes the time diff between
	// current time and LastUpdatedTime to exceed staleHours; 3) The number
	// of commits that Gitiles git.Log API returns equals to
	// MaxCommitsPerRefUpdate.
	Paused bool

	// AcceptedOverwriteLastKnownCommit saves those OverwriteLastKnownCommit
	// which have already been used for unpausing a ref.
	AcceptedOverwriteLastKnownCommit string

	// This is the key of the configuration in RuleMap that applies to
	// this git ref. Note that each ref can only be matched to one such
	// configuration.
	ConfigName string

	// These are overridden in the repo config differently for each ref.
	Metadata   string
	BranchName string
}

RepoState contains the state for each ref we audit. Including parameters applicable to dynamically configured refs.

type RevertOfCulprit

type RevertOfCulprit struct {
	*cpb.RevertOfCulprit
}

RevertOfCulprit is a Rule that verifies that the reverting commit is a revert of the named culprit.

func (RevertOfCulprit) GetName

func (rule RevertOfCulprit) GetName() string

GetName returns the name of the rule

func (RevertOfCulprit) Run

Run executes the rule.

type Role

type Role uint8

Role is an enum describing the relationship between an email account and a commit. (Such as Committer or Author)

const (
	// Committer is when the account is present in the committer field of
	// the commit.
	Committer Role = iota

	// Author is when the account is present in the author field of the
	// commit.
	Author
)

type Rule

type Rule interface {
	// GetName returns the name of the rule as a string. It is expected to be unique in
	// each repository it applies to.
	GetName() string
	// Run performs a check according to the Rule.
	//
	// This could be called multiple times on the same commit if the rule fails,
	// and needs to be retried or if the rule ran previously and resulted in a
	// non-final state. Rules should self-limit the frequency with which they poll
	// external systems for a given commit.
	//
	// Rules are expected to return an error if they cannot determine whether a policy
	// has been broken or not.
	//
	// Run methods should return a reference to a RuleResult
	Run(context.Context, *AuditParams, *RelevantCommit, *Clients) (*RuleResult, error)
}

Rule is an audit rule.

It has a name getter and a rule implementation.

type RuleResult

type RuleResult struct {
	RuleName         string
	RuleResultStatus RuleStatus
	Message          string
	// Freeform string that can be used by rules to pass data to notifiers.
	// Notably used by the .GetToken and .SetToken methods.
	MetaData string `gae:",noindex"`
}

RuleResult represents the result of applying a single rule to a commit.

func OnlyModifiesPathsRuleImpl

func OnlyModifiesPathsRuleImpl(ctx context.Context, ap *AuditParams, rc *RelevantCommit, cs *Clients, paths []*Path) (*RuleResult, error)

OnlyModifiesPathsRuleImpl is a shared implementation for Rules which verify that only the given path(s) are modified by the audited CL.

func PreviousResult

func PreviousResult(ctx context.Context, rc *RelevantCommit, ruleName string) *RuleResult

PreviousResult returns the result for a previous application of the rule on the given commit or nil.

func (*RuleResult) GetToken

func (rr *RuleResult) GetToken(ctx context.Context, tokenName string) (string, bool)

GetToken is a convenience method to get tokens from a RuleResult's MetaData. exists (as opposed to the token being the empty string). Assumes rr.MetaData is a \n separated list of "key:value" strings, used by rules to specify details of the notification not conveyed in the .Message field.

func (*RuleResult) SetToken

func (rr *RuleResult) SetToken(ctx context.Context, tokenName, tokenValue string) error

SetToken is a convenience method to set tokens on a RuleResult's MetaData. Assumes rr.MetaData is a \n separated list of "key:value" strings, used by rules to specify details of the notification not conveyed in the .Message field.

type RuleStatus

type RuleStatus int

RuleStatus is the enum for RuleResult.RuleResultStatus.

const (
	// RuleFailed is the status when a rule has failed.
	RuleFailed RuleStatus = iota
	// RulePassed is the status when a rule has passed.
	RulePassed
	// RuleSkipped is the status when a rule has been skipped.
	RuleSkipped
	// NotificationRequired is the status when a rule requires notifications.
	NotificationRequired
	// RulePending is the status when a rule's result cannot be decided.
	RulePending
	// RuleInvalid is an invalid value, for testing.
	RuleInvalid
)

func (RuleStatus) ColorCode

func (rs RuleStatus) ColorCode() string

ColorCode returns a stirng used to color code the string, as a css class for example.

func (RuleStatus) ToString

func (rs RuleStatus) ToString() string

ToString returns a human-readable version of this status.