buildbucket/proto/rpc.proto

// Copyright 2018 The Swarming Authors. All rights reserved.
// Use of this source code is governed by the Apache v2.0 license that can be
// found in the LICENSE file.

syntax = "proto3";

package buildbucket.v2;

option go_package = "go.chromium.org/luci/buildbucket/proto;buildbucketpb";

import "google/protobuf/field_mask.proto";
import "google/protobuf/struct.proto";
import "google/rpc/status.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";
import "go.chromium.org/luci/buildbucket/proto/build.proto";
import "go.chromium.org/luci/buildbucket/proto/notification.proto";

// Manages builds.
//
// Buildbot: To simplify V1->V2 API transition for clients, buildbucket.v2.Builds
// service has some support for non-LUCI builds. Most of such builds are
// Buildbot builds and this documentation refers to them as such, but they also
// include non-Buildbot non-LUCI builds (e.g. Skia builds).
// See "Buildbot" paragraph in each RPC comment.
service Builds {
  // Gets a build.
  //
  // By default the returned build does not include all fields.
  // See GetBuildRequest.fields.
  //
  // Buildbot: if the specified build is a buildbot build, converts it to Build
  // message with the following rules:
  // * bucket names are full, e.g. "master.chromium". Note that LUCI buckets
  //   in v2 are shortened, e.g. "ci".
  // * if a v2 Build field does not make sense in V1, it is unset/empty.
  // * step support is not implemented for Buildbot builds.
  // Note that it does not support getting a buildbot build by build number.
  rpc GetBuild(GetBuildRequest) returns (Build) {};

  // Searches for builds.
  //
  // Buildbot: can return Buildbot builds, see GetBuild for conversion rules.
  // For example, response may include a mix of LUCI and Buildbot builds if the
  // predicate is a CL.
  // Cannot search in a buildbot bucket or buildbot builder, e.g.
  // {
  //   "predicate": {
  //     "builder": {
  //       "project": "chromium",
  //       "bucket": "master.chromium",
  //       "builder": "linux-rel"
  //     }
  //   }
  // }
  // will look for builds in "master.chromium" LUCI bucket which probably does
  // not exist.
  rpc SearchBuilds(SearchBuildsRequest) returns (SearchBuildsResponse) {};

  // Executes multiple requests in a batch.
  // The response code is always OK.
  rpc Batch(BatchRequest) returns (BatchResponse) {};

  // Updates a build.
  // Returns updated build. Response includes only the fields
  // included by default in GetBuild and updated fields.
  //
  // RPC metadata must include "X-Build-Token" key with a token
  // generated by the server when scheduling the build.
  rpc UpdateBuild(UpdateBuildRequest) returns (Build) {};

  // Schedules a new build.
  // The requester must have at least SCHEDULER role in the destination bucket.
  rpc ScheduleBuild(ScheduleBuildRequest) returns (Build) {};
}

// A request message for GetBuild rpc.
message GetBuildRequest {
  // Build id.
  // Mutually exclusive with builder and number.
  int64 id = 1;

  // Builder of the build.
  // Requires number. Mutually exclusive with id.
  BuilderID builder = 2;
  // Build number.
  // Requires builder. Mutually exclusive with id.
  int32 build_number = 3;

  // Fields to include in the response.
  // If not set, the default mask is used, see Build message comments for the
  // list of fields returned by default.
  //
  // Supports advanced semantics, see
  // https://chromium.googlesource.com/infra/luci/luci-py/+/f9ae69a37c4bdd0e08a8b0f7e123f6e403e774eb/appengine/components/components/protoutil/field_masks.py#7
  // In particular, if the client needs only some output properties, they
  // can be requested with paths "output.properties.fields.foo".
  google.protobuf.FieldMask fields = 100;
}

// A request message for SearchBuilds rpc.
message SearchBuildsRequest {
  // Returned builds must satisfy this predicate. Required.
  BuildPredicate predicate = 1;

  // Fields to include in the response, see GetBuildRequest.fields.
  // Note that this applies to the response, not each build, so e.g. steps must
  // be requested with a path "builds.*.steps".
  google.protobuf.FieldMask fields = 100;

  // Number of builds to return.
  // Defaults to 100.
  // Any value >1000 is interpreted as 1000.
  int32 page_size = 101;

  // Value of SearchBuildsResponse.next_page_token from the previous response.
  // Use it to continue searching.
  string page_token = 102;
}

// A response message for SearchBuilds rpc.
message SearchBuildsResponse {
  // Search results.
  //
  // Ordered by build id, descending. Ids are monotonically decreasing, so in
  // other words the order is newest-to-oldest.
  repeated Build builds = 1;

  // Value for SearchBuildsRequest.page_token to continue searching.
  string next_page_token = 100;
}

// A request message for Batch rpc.
message BatchRequest {

  // One request in a batch.
  message Request {
    oneof request {
      // GetBuild RPC.
      GetBuildRequest get_build = 1;
      // SearchBuilds RPC.
      SearchBuildsRequest search_builds = 2;
    }
  }

  // Requests to execute in a single batch.
  //
  // Requests related to same build are coupled.
  // Mutation requests are executed transactionally, before read-only requests.
  repeated Request requests = 1;
}

// A response message for Batch rpc.
message BatchResponse {

  // Response a BatchRequest.Response.
  message Response {
    oneof response {
      // GetBuild RPC response.
      Build get_build = 1;
      // SearchBuilds RPC response.
      SearchBuildsResponse search_builds = 2;

      // Error code and details of the unsuccessful RPC.
      google.rpc.Status error = 100;
    }
  }

  // Responses in the same order as BatchRequest.requests.
  repeated Response responses = 1;
}

// A request message for UpdateBuild rpc.
message UpdateBuildRequest {
  // Build to update, with new field values.
  Build build = 1;

  // Build fields to update.
  // See also
  // https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask
  //
  // Currently only "build.steps" path is supported.
  google.protobuf.FieldMask update_mask = 2;

  // Fields to include in the response. See also GetBuildRequest.fields.
  google.protobuf.FieldMask fields = 100;
}

// A request message for ScheduleBuild rpc.
//
// Next ID: 13.
message ScheduleBuildRequest {
  // Required. A unique string id used for detecting duplicate requests.
  // Should be unique at least per requesting identity.
  // Used to dedup build scheduling requests with same id within 1 min.
  // If a build was successfully scheduled with the same request id in the past
  // minute, the existing build will be returned.
  string request_id = 1;

  // Value for Build.builder. See its comments.
  //
  // Mutually exclusive with template_build_id.
  BuilderID builder = 2;

  // ID of a build to retry as is or altered.
  // When specified, other fields in this message default to the values in the
  // template build.
  //
  // Mutually exclusive with builder.
  int64 template_build_id = 3;

  // If specified, overrides server-defined value of
  // Build.infra.buildbucket.canary.
  // Otherwise the value is computed based on the builder config.
  // See Swarming.task_template_canary_percentage in
  // ./config/project_config.proto.
  Trinary canary = 4;

  // If specified, overrides server-defined value of Build.input.experimental.
  // Otherwise the value is computed based on the builder config.
  // See Builder.experimental in ./config/project_config.proto.
  Trinary experimental = 5;

  // Properties to include in Build.input.properties.
  //
  // Input properties of the created build are result of merging server-defined
  // properties and properties in this field.
  // Each property in this field defines a new or replaces an existing property
  // on the server.
  // If the server config does not allow overriding/adding the property, the
  // request will fail with InvalidArgument error code.
  // A server-defined property cannot be removed, but its value can be
  // replaced with null.
  //
  // Reserved property paths:
  // * ["buildbucket"]
  // * ["buildername"]
  // * ["blamelist""]
  // * ["$recipe_engine/runtime", "is_luci"]
  // * ["$recipe_engine/runtime", "is_experimental"]
  //
  // V1 equivalent: corresponds to "properties" key in "parameters_json".
  google.protobuf.Struct properties = 6;

  // Value for Build.input.gitiles_commit.
  //
  // V1 equivalent: supersedes "revision" property and "buildset"
  // tag that starts with "commit/gitiles/".
  GitilesCommit gitiles_commit = 7;

  // Value for Build.input.gerrit_changes.
  // Usually present in tryjobs, set by CQ, Gerrit, git-cl-try.
  // Applied on top of gitiles_commit if specified, otherwise tip of the tree.
  //
  // V1 equivalent: supersedes patch_* properties and "buildset"
  // tag that starts with "patch/gerrit/".
  repeated GerritChange gerrit_changes = 8;

  // Tags to include in Build.tags of the created build, see Build.tags
  // comments.
  // Note: tags of the created build may include other tags defined on the
  // server.
  repeated StringPair tags = 9;

  // Overrides default dimensions defined by builder config or template build.
  //
  // A set of entries with the same key defines a new or replaces an existing
  // dimension with the same key.
  // If the config does not allow overriding/adding the dimension, the request
  // will fail with InvalidArgument error code.
  //
  // After merging, dimensions with empty value will be excluded.
  repeated StringPair dimensions = 10;

  // If not zero, overrides swarming task priority.
  // See also Build.infra.swarming.priority.
  int32 priority = 11;

  // A per-build notification configuration.
  NotificationConfig notify = 12;

  // Fields to include in the response. See also GetBuildRequest.fields.
  google.protobuf.FieldMask fields = 100;
}

// A build predicate.
//
// At least one of the following fields is required: builder, gerrit_changes and
// git_commits..
// If a field value is empty, it is ignored, unless stated otherwise.
message BuildPredicate {
  // A build must be in this builder.
  BuilderID builder = 1;

  // A build must have this status.
  Status status = 2;

  // A build's Build.Input.gerrit_changes must include ALL of these changes.
  repeated GerritChange gerrit_changes = 3;

  // A build's Build.Output.gitiles_commit must match this commit.
  // One of the following subfield sets must specified:
  // - host, project, id
  // - host, project, ref
  GitilesCommit output_gitiles_commit = 4;

  // A build must be created by this identity.
  string created_by = 5;

  // A build must have ALL of these tags.
  // For "ANY of these tags" make separate RPCs.
  repeated StringPair tags = 6;

  // A build must have been created within the specified range.
  // Both boundaries are optional.
  TimeRange create_time = 7;

  // If false (default), a build must be non-experimental.
  // Otherwise it may be experimental or non-experimental.
  bool include_experimental = 8;

  // A build must be in this build range.
  // A pair of SearchBuildsRequest.predicate.build.end_build_id and
  // SearchBuildsRequest.page_size=1 can be used to find the previous build.
  BuildRange build = 9;
}

// Half-open build range.
// The range is defined on the build order in the context.
// Usually the order is newest-to-oldest, so start_build_id is a newer
// build and end_build_id is an older build.
message BuildRange {
  // Inclusive lower boundary. Optional.
  int64 start_build_id = 1;
  // Exclusive upper boundary. Optional.
  int64 end_build_id = 2;
}