milo/common/model/build_summary.go

// Copyright 2017 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package model

import (
	"bytes"
	"time"

	"github.com/luci/gae/service/datastore"

	"github.com/luci/luci-go/common/data/cmpbin"
)

// BuildSummary is a datastore model which is used for storing staandardized
// summarized build data, and is used for backend-agnostic views (i.e. builders,
// console). It contains only data that:
//   * is necessary to render these simplified views
//   * is present in all implementations (buildbot, buildbucket)
//
// This entity will live as a child of the various implementation's
// representations of a build (e.g. buildbotBuild). It has various 'tag' fields
// so that it can be queried by the various backend-agnostic views.
type BuildSummary struct {
	// _id for a BuildSummary is always 1
	_ int64 `gae:"$id,1"`

	// BuildKey will always point to the "real" build, i.e. a buildbotBuild or
	// a buildbucketBuild. It is always the parent key for the BuildSummary.
	BuildKey *datastore.Key `gae:"$parent"`

	// Global identifier for the builder that this Build belongs to, i.e.:
	//   "buildbot/<mastername>/<buildername>"
	//   "buildbucket/<bucketname>/<buildername>"
	BuilderID string

	// Created is the time when the Build was first created. Due to pending
	// queues, this may be substantially before Summary.Start.
	Created time.Time

	// Summary summarizes relevant bits about the overall build.
	Summary Summary

	// CurrentStep summarizes relevant bits about the currently running step (if
	// any). Only expected to be set if !Summary.Status.Terminal().
	CurrentStep Summary

	// Manifests is a list of links to source manifests that this build reported.
	Manifests []ManifestLink

	// Patches is the list of patches which are associated with this build.
	// We reserve the multi-patch case for advanced (multi-repo) tryjobs...
	// Typically there will only be one patch associated with a build.
	Patches []PatchInfo

	// ManifestRevisionIndex has a single entry for each
	//   0 ++ project ++ console ++ manifest_name ++ url ++ revision.decode('hex')
	// which matched for this build. ++ is cmpbin concatenation.
	//
	// Example:
	//   0 ++ "chromium" ++ "main" ++ "UNPATCHED" ++ "https://.../src.git" ++ deadbeef
	//
	// The list of interested consoles is compiled at build summarization time.
	ManifestRevisionIndex [][]byte
}

// AddManifestRevisionIndex adds a new entry to ManifestRevisionIndex.
//
// `revision` should be the hex-decoded git revision.
//
// It's up to the caller to ensure that entries in ManifestRevisionIndex aren't
// duplicated.
func (bs *BuildSummary) AddManifestRevisionIndex(project, console, manifest, repoURL string, revision []byte) {
	var buf bytes.Buffer
	cmpbin.WriteUint(&buf, 0) // version
	cmpbin.WriteString(&buf, project)
	cmpbin.WriteString(&buf, console)
	cmpbin.WriteString(&buf, manifest)
	cmpbin.WriteString(&buf, repoURL)
	cmpbin.WriteBytes(&buf, revision)
	bs.ManifestRevisionIndex = append(bs.ManifestRevisionIndex, buf.Bytes())
}