go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/milo/proto/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_common.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";
import "go.chromium.org/luci/milo/proto/projectconfig/project.proto";

option go_package = "go.chromium.org/luci/milo/proto/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) {};

  // Retrieves a list of projects.
  rpc ListProjects(ListProjectsRequest) returns (ListProjectsResponse) {};

  // Gets the project config.
  //
  // Return the config of the project.
  rpc GetProjectCfg(GetProjectCfgRequest) returns (luci.milo.projectconfig.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) {};

  // Get the statistics associated with a builder.
  rpc QueryBuilderStats(QueryBuilderStatsRequest) returns (BuilderStats) {};

  // Check whether the users has the specified permissions in the given realm.
  rpc BatchCheckPermissions(BatchCheckPermissionsRequest) returns (BatchCheckPermissionsResponse) {};

  // Retrieves a list of consoles.
  rpc QueryConsoles(QueryConsolesRequest) returns (QueryConsolesResponse) {};

  // Retrieves a list of consoles with latest snapshots.
  rpc QueryConsoleSnapshots(QueryConsoleSnapshotsRequest) returns (QueryConsoleSnapshotsResponse) {};
}

// 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;

  // This field is unused.
  //
  // TODO(crbugs/1047893): remove this field in the once no clients depends on
  // this.
  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;
}

// A request message for `ListProjects` RPC.
message ListProjectsRequest {
  // Optional. The maxium number of projects to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 projects will be returned.
  // The maximum value is 10000; values above 10000 will be coerced to 10000.
  int32 page_size = 1;

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

// A response message for `ListProjects` RPC.
message ListProjectsResponse {
  // A list of matched projects.
  //
  // Projects are ordered by their string ID
  repeated ProjectListItem projects = 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 single project in a ListProjectsResponse.
message ProjectListItem {
  // The project id.
  string id = 1;

  // The url of the project logo.
  string logo_url = 2;
}

// A stateless page token for `ListProjects` RPC.
message ListProjectsPageToken {
  // The index of the next project from all projects.
  int32 next_project_index = 3;
}

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 only when `group` is specified. The project to query the builders
  // from.
  //
  // When specified, query all builders in the project as well as any external
  // builders  referenced by the consoles in the project.
  // When omitted, query all builders in any project.
  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 10000; values above 10000 will be coerced to 10000.
  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.
  //
  // Builders are ordered by their canonical string ID
  // (i.e. "{project}/{bucket}/{builder}") with the exception that builders from
  // `ListBuildersRequest.project` always come before builders from other
  // projects.
  // 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;
}

// A stateless page token for `ListBuilders` RPC.
message ListBuildersPageToken {
  // The index of the next builder from all cached builders from buildbucket.
  //
  // Should not coexist with `NextMiloBuilderIndex`.
  int32 next_buildbucket_builder_index = 3;
  // The index of the next builder from Milo project definition.
  //
  // Should not coexist with `NextBuildbucketBuilderIndex`.
  int32 next_milo_builder_index = 2;
}

// A request message for `QueryBuilderStats` RPC.
message QueryBuilderStatsRequest {
  // The builder to query the stats from.
  buildbucket.v2.BuilderID builder = 1;
}

// A message that contains some basic stats of a builder.
message BuilderStats {
  // The builder that the stats belongs to.
  buildbucket.v2.BuilderID builder = 1;

  // The number of pending builds associated with the builder.
  int32 pending_builds_count = 2;

  // The number of running builds associated with the builder.
  int32 running_builds_count = 3;
}

// A request message for `BatchCheckPermissions` RPC.
message BatchCheckPermissionsRequest {
  // Required. The realm to check the permissions against.
  string realm = 1;

  // String representation of the permissions.
  //
  // Permissions must have the following format: `<service>.<subject>.<verb>`.
  repeated string permissions = 2;
}

// A response message for `BatchCheckPermissions` RPC.
message BatchCheckPermissionsResponse {
  // A map of permission check results.
  //
  // The key is the permission name and the value is whether the user has the
  // permission.
  map<string, bool> results = 1;
}

// Represents a function Console -> bool.
// Empty message matches all consoles.
message ConsolePredicate {
  // A console must belong to this project.
  string project = 2;

  // A console must include this builder.
  buildbucket.v2.BuilderID builder = 1;
}

message QueryConsolesRequest {
  // A console in the response must satisfy this predicate.
  ConsolePredicate predicate = 1;

  // Optional. The maxium number of consoles to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 25 consoles 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 `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 = 3;
}

message QueryConsolesResponse {
  // A list of matched consoles.
  repeated luci.milo.projectconfig.Console consoles = 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;
}

message QueryConsoleSnapshotsRequest {
  // A console in the response must satisfy this predicate.
  // `predicate.project` is required.
  ConsolePredicate predicate = 1;

  // Optional. The maximum number of consoles to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 25 consoles 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 `QueryConsoleSnapshots`
  // call. Provide this to retrieve the subsequent page.
  //
  // When paginating, all parameters provided to `QueryConsoleSnapshots`, with
  // the exception of page_size and page_token, must match the call that
  // provided the page token.
  string page_token = 3;
}

message BuilderSnapshot {
  // The builder this snapshot belongs to.
  buildbucket.v2.BuilderID builder = 1;

  // The latest build associated with the builder at the time the snapshot is
  // taken. Nil if there's no associated build.
  buildbucket.v2.Build build = 2;
}

message ConsoleSnapshot {
  // The console this snapshot belongs to.
  luci.milo.projectconfig.Console console = 1;

  // The snapshots of all the builders in the console.
  // In the same order as `console.builders`.
  repeated BuilderSnapshot builder_snapshots = 2;
}


message QueryConsoleSnapshotsResponse {
  // A list of matched consoles.
  repeated ConsoleSnapshot snapshots = 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;
}