gobmap

Documentation

Overview

Package gobmap finds relevant LUCI project config given a Gerrit CL.

gobmap constructs the map based on LUCI project's ConfigGroups, and supports efficiently updating the map whenever Project configs change.

Index

• func Lookup(ctx context.Context, host, repo, ref string) (*changelist.ApplicableConfig, error)
• func LookupProjects(ctx context.Context, host, repo string) ([]string, error)
• func Update(ctx context.Context, meta *prjcfg.Meta, cgs []*prjcfg.ConfigGroup) error

Functions

func Lookup

func Lookup(ctx context.Context, host, repo, ref string) (*changelist.ApplicableConfig, error)

Lookup returns config group IDs which watch the given combination of Gerrit host, repo and ref.

For example: the input might be ("chromium-review.googlesource.com", "chromium/src", "refs/heads/main"), and the output might be 0 or 1 or multiple IDs which can be used to fetch config groups.

Due to the ref_regexp[_exclude] options, CV can't ensure that each possible combination is watched by at most one ConfigGroup, which is why this may return multiple ConfigGroupIDs even for the same LUCI project.

Always returns non-nil object, even if there are no watching projects.

func LookupProjects

func LookupProjects(ctx context.Context, host, repo string) ([]string, error)

LookupProjects returns all the LUCI projects that have at least one applicable config for a given host and repo.

Returns a sorted slice with a unique set of the LUCI projects.

func Update

func Update(ctx context.Context, meta *prjcfg.Meta, cgs []*prjcfg.ConfigGroup) error

Update updates the gob map entities according to the given project config.

This may include adding, removing and modifying entities, which is not done atomically. Changes to individual Gerrit repos are atomic. This means that IF Update() is in progress from config versions 1 to 2, identified by

hashes h1 and h2, respectively,

AND both h1 and h2 watch specific Gerrit repo, possibly among many others, THEN a concurrent Lookup(host,repo,...) is guaranteed to return either based on @h1 or based on @h2.

However, there is no atomicity across entire project config. This means that IF Update() is in progress from config versions 1 to 2, identified by

hashes h1 and h2, respectively,

THEN two sequential calls to Lookup with different Gerrit repos may return results based on @h2 at first and @h1 for the second, ie:

Lookup(host1,repoA,...) -> @h2
Lookup(host1,repoB,...) -> @h1

Thus, a failed Update() may leave gobmap in a corrupted state, whereby some Gerrit repos may represent old and some new config versions. In such a case it's important that Update() caller retries as soon as possible.

TODO(crbug.com/1179286): make Update() incorruptible. See TestGobMapConcurrentUpdates which reproduces corruption.

Update is idempotent.