// Copyright 2020 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/api/field_behavior.proto";
import "go.chromium.org/luci/buildbucket/proto/builder.proto";

// Provides preconfigured builders.
service Builders {
  // Looks up one builder.
  rpc GetBuilder(GetBuilderRequest) returns (BuilderItem) {};

  // Lists all builders of a project or a bucket.
  rpc ListBuilders(ListBuildersRequest) returns (ListBuildersResponse) {};
}

// A request message for GetBuilder rpc.
message GetBuilderRequest {
  // ID of the builder to return.
  BuilderID id = 1;
}

// A request message for ListBuilders.
message ListBuildersRequest {
  // LUCI project, e.g. "chromium".
  string project = 1  [ (google.api.field_behavior) = REQUIRED ];

  // A bucket in the project, e.g. "try".
  string bucket = 2;

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

  // A page token, received from a previous `ListBuilders` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListBuilders` MUST
  // match the call that provided the page token.
  string page_token = 4;
}

// A response message for ListBuilders.
message ListBuildersResponse {
  // Matched builders.
  repeated BuilderItem builders = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  // If the invocation is not finalized, more results may appear later.
  string next_page_token = 2;
}