go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/buildbucket/proto/builder_service.proto (about)

     1  // Copyright 2020 The Swarming Authors. All rights reserved.
     2  // Use of this source code is governed by the Apache v2.0 license that can be
     3  // found in the LICENSE file.
     4  
     5  syntax = "proto3";
     6  
     7  package buildbucket.v2;
     8  
     9  option go_package = "go.chromium.org/luci/buildbucket/proto;buildbucketpb";
    10  
    11  import "google/api/field_behavior.proto";
    12  import "google/protobuf/empty.proto";
    13  import "google/rpc/status.proto";
    14  import "go.chromium.org/luci/buildbucket/proto/builder_common.proto";
    15  import "go.chromium.org/luci/buildbucket/proto/common.proto";
    16  
    17  // Provides preconfigured builders.
    18  service Builders {
    19    // Looks up one builder.
    20    rpc GetBuilder(GetBuilderRequest) returns (BuilderItem) {};
    21  
    22    // Lists all builders of a project or a bucket.
    23    rpc ListBuilders(ListBuildersRequest) returns (ListBuildersResponse) {};
    24  
    25    // SetBuilderHealth allows a Builder's health to be set.
    26    rpc SetBuilderHealth(SetBuilderHealthRequest) returns (SetBuilderHealthResponse) {};
    27  }
    28  
    29  // A request message for GetBuilder rpc.
    30  message GetBuilderRequest {
    31    // ID of the builder to return.
    32    BuilderID id = 1;
    33  
    34    // Mask for which fields to include in the response.
    35    //
    36    // If not set, the default mask is CONFIG_ONLY.
    37    BuilderMask mask = 2;
    38  }
    39  
    40  // A request message for ListBuilders.
    41  message ListBuildersRequest {
    42    // LUCI project, e.g. "chromium". Omit to list all builders.
    43    //
    44    // Required when bucket is specified.
    45    string project = 1;
    46  
    47    // A bucket in the project, e.g. "try".
    48    //
    49    // Omit to list all builders or all builders in a project.
    50    string bucket = 2;
    51  
    52    // The maximum number of builders to return.
    53    //
    54    // The service may return fewer than this value.
    55    // If unspecified, at most 100 builders will be returned.
    56    // The maximum value is 1000; values above 1000 will be coerced to 1000.
    57    int32 page_size = 3;
    58  
    59    // A page token, received from a previous `ListBuilders` call.
    60    // Provide this to retrieve the subsequent page.
    61    //
    62    // When paginating, all other parameters provided to `ListBuilders` MUST
    63    // match the call that provided the page token.
    64    string page_token = 4;
    65  }
    66  
    67  // A response message for ListBuilders.
    68  message ListBuildersResponse {
    69    // Matched builders.
    70    repeated BuilderItem builders = 1;
    71  
    72    // A token, which can be sent as `page_token` to retrieve the next page.
    73    // If this field is omitted, there were no subsequent pages at the time of
    74    // request.
    75    // If the invocation is not finalized, more results may appear later.
    76    string next_page_token = 2;
    77  }
    78  
    79  // A request message for SetBuilderHealth RPC.
    80  message SetBuilderHealthRequest {
    81    // BuilderHealth needs BuilderID so that SetBuilderHealth RPC can properly update
    82    // the Builder datastore entity with the updated HealthStatus.
    83    message BuilderHealth {
    84      // Required. Builder to set the health score for.
    85      // You must have the 'buildbucket.builders.set_health' permission for
    86      // each of them.
    87      BuilderID id = 1 [(google.api.field_behavior) = REQUIRED];
    88  
    89      // Required. Health status of the builder.
    90      HealthStatus health = 2 [(google.api.field_behavior) = REQUIRED];
    91    }
    92  
    93    repeated BuilderHealth health = 1;
    94  }
    95  
    96  // A response message for SetBuilderHealth RPC.
    97  message SetBuilderHealthResponse {
    98    message Response {
    99      oneof response {
   100        google.protobuf.Empty result = 1;
   101        google.rpc.Status error = 100;
   102      }
   103    }
   104  
   105    // Responses should be empty protos or errors. They will map
   106    // directly with the repeated health fields from SetBuilderHealthRequest.
   107    repeated Response responses = 1;
   108  }
   109  
   110  message BuilderMask {
   111    enum BuilderMaskType {
   112      BUILDER_MASK_TYPE_UNSPECIFIED = 0;
   113  
   114      // Default. Returns ID + Config fields in BuilderItem.
   115      CONFIG_ONLY = 1;
   116  
   117      // Returns all fields in BuilderItem.
   118      ALL = 2;
   119  
   120      // Returns ID + METADATA fields in BuilderItem.
   121      METADATA_ONLY = 3;
   122    }
   123  
   124    // Type of mask to use to filter BuilderItem.
   125    BuilderMaskType type = 1;
   126  }