milo/api/service/v1/rpc.proto

// Copyright 2020 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.

syntax = "proto3";

package luci.milo.v1;

import "go.chromium.org/luci/common/proto/git/commit.proto";
import "go.chromium.org/luci/buildbucket/proto/build.proto";
import "go.chromium.org/luci/buildbucket/proto/builder.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";
import "go.chromium.org/luci/milo/api/config/project.proto";

option go_package = "go.chromium.org/luci/milo/api/service/v1;milopb";

// Service to query data on the Milo server.
//
// Note: this is private API and should only be used by Milo apps. Breaking
// changes might be introduced without notice.
// Please contact chops-luci-test@ if your code needs to depend on this service.
service MiloInternal {
  // Retrieves blamelist of a build.
  //
  // The blamelist of a build is defined as [end_commit, start_commit)
  // end_commit is the Gitiles commit of the build (specified in gitiles
  // buildset tag).
  // start_commit is the closest ancestor commit with an associated build that
  // is from the same builder and is not expired, cancelled, or infra-failed.
  rpc QueryBlamelist(QueryBlamelistRequest) returns (QueryBlamelistResponse) {};

  // Gets the project config.
  //
  // Return the config of the project.
  rpc GetProjectCfg(GetProjectCfgRequest) returns (.milo.Project) {};

  // Retrieves the recent, finished builds of a builder.
  rpc QueryRecentBuilds(QueryRecentBuildsRequest) returns (QueryRecentBuildsResponse) {};

  // Retrieves a list of builders in a project or a builder group.
  rpc ListBuilders(ListBuildersRequest) returns (ListBuildersResponse) {};
}

// A request message for `QueryBlamelist` RPC.
message QueryBlamelistRequest {
  // The Gitiles commit of the build.
  //
  // This defines the end_commit of the blamelist.
  // It should be set to the output Gitiles commit of the build.
  // Input Gitiles commit should be used when output gitiles commit is not
  // available.
  buildbucket.v2.GitilesCommit gitiles_commit = 1;

  // The context builder of the blamelist.
  //
  // The start commit of the blamelist is the closest ancestor commit with an
  // associated build that is from the same builder and is not expired,
  // cancelled, or infra-failed.
  buildbucket.v2.BuilderID builder = 2;

  // Optional. The maximum number of commits to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 commits will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 3;

  // Optional. A page token, received from a previous `QueryBlamelist` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all parameters provided to `QueryBlamelist`, with the
  // exception of page_size and page_token, must match the call that provided
  // the page token.
  string page_token = 4;

  // Enable multi-project support.
  //
  // When set to false (default), BuildSummary.BuildSets will be used to find
  // the closest ancestor commit with an associated build.
  // When set to true, BuildSummary.BlamelistPins will be used instead. Older
  // builds may not have BlamelistPins populated.
  // TODO(crbugs/1047893): once all recent builds have BlamelistPins populated,
  // remove this flag and use BlamelistPins unconditionally.
  bool multi_project_support = 5;
}

// A response message for QueryBlamelist RPC.
message QueryBlamelistResponse {
  // The commits from the blamelist of the build, in reverse chronological
  // order.
  repeated git.Commit commits = 1;

  // A token that can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;

  // The repo commit immediately preceding |commits|. Useful for creating
  // git log queries, which are exclusive of the first commit.
  // Unset when |commits| includes the first commit in the repository.
  git.Commit preceding_commit = 3;
}

// A stateless page token for QueryBlamelist RPC.
message QueryBlamelistPageToken {
  // The first commit in the next page.
  string next_commit_id = 2;
}

message GetProjectCfgRequest {
  // The project name.
  string project = 1;
}

// A request message for `QueryRecentBuilds` RPC.
message QueryRecentBuildsRequest {
  // The builder to query the build history from.
  buildbucket.v2.BuilderID builder = 1;

  // Optional. The maxium number of builds to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 25 builds will be returned.
  // The maximum value is 100; values above 100 will be coerced to 100.
  int32 page_size = 2;

  // Optional. A page token, received from a previous `QueryRecentBuilds`
  // call. Provide this to retrieve the subsequent page.
  //
  // When paginating, all parameters provided to `QueryRecentBuilds`, with
  // the exception of page_size and page_token, must match the call that
  // provided the page token.
  string page_token = 3;
}

// A response message for `QueryRecentBuilds` RPC.
message QueryRecentBuildsResponse {
  // Recent builds. Ordered by `CreateTime`.
  // Only Id, Builder, Number, CreateTime, Status, Critical are populated.
  repeated buildbucket.v2.Build builds = 1;

  // A token that can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// A request message for `ListBuilders` RPC.
message ListBuildersRequest {
  // Required. The project to query the builders from.
  string project = 1;

  // Optional. The group/console to query the builders from.
  //
  // When omitted, all builders from the project is returned. Including all
  // builders defined in the consoles, builder groups, and buildbucket.
  string group = 2;

  // Optional. The maxium number of builders to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 builders will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 3;

  // Optional. A page token, received from a previous `ListBuilders`
  // call. Provide this to retrieve the subsequent page.
  //
  // When paginating, all parameters provided to `ListBuilders`, with the
  // exception of page_size and page_token, must match the call that provided
  // the page token.
  string page_token = 4;
}

// A response message for `ListBuilders` RPC.
message ListBuildersResponse {
  // A list of matched builders.
  //
  // Only builder IDs are populated for now.
  repeated buildbucket.v2.BuilderItem builders = 1;

  // A token that can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}