// Copyright 2020 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

syntax = "proto3";

package monorail.v3;

option go_package = "infra/monorailv2/api/v3/api_proto";

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "api/v3/api_proto/user_objects.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";

// ***ONLY CALL rpcs WITH `status: {ALPHA|STABLE}`***
// rpcs without `status` are not ready.

// Users service includes all methods needed for managing Users.
service Users {
  // status: ALPHA
  // Returns the requested User.
  //
  // Raises:
  //   NOT_FOUND is the user is not found.
  //   INVALID_ARGUMENT if the `name` is invalid.
  rpc GetUser (GetUserRequest) returns (User) {}

  // status: ALPHA
  // Returns all of the requested Users.
  //
  // Raises:
  //   NOT_FOUND if any users are not found.
  //   INVALID_ARGUMENT if any `names` are invalid.
  rpc BatchGetUsers (BatchGetUsersRequest) returns (BatchGetUsersResponse) {}

  // status: NOT READY
  // Updates a User.
  //
  // Raises:
  //   NOT_FOUND if the user is not found.
  //   PERMISSION_DENIED if the requester is not allowed to update the user.
  //   INVALID_ARGUMENT if required fields are missing or fields are invalid.
  rpc UpdateUser (UpdateUserRequest) returns (User) {}

  // status: NOT READY
  // Stars a given project for the requestor.
  //
  // Raises:
  //   NOT_FOUND if the requested project is not found.
  //   INVALID_ARGUMENT if the given `project` is not valid.
  rpc StarProject (StarProjectRequest) returns (ProjectStar) {}

  // status: NOT READY
  // Unstars a given project for the requestor.
  //
  // Raises:
  //   NOT_FOUND if the requested project is not found.
  //   INVALID_ARGUMENT if the given `project` is not valid.
  rpc UnStarProject (UnStarProjectRequest) returns (google.protobuf.Empty) {}

  // status: NOT READY
  // Lists all of a user's starred projects.
  //
  // Raises:
  //   NOT_FOUND if the requested user is not found.
  //   INVALID_ARGUMENT if the given `parent` is not valid.
  rpc ListProjectStars (ListProjectStarsRequest) returns (ListProjectStarsResponse) {}
}


// The request message for Users.GetUser.
// Next available tag: 2
message GetUserRequest {
  // The name of the user to request.
  string name = 1 [
      (google.api.resource_reference) = {type: "api.crbug.com/User"},
      (google.api.field_behavior) = REQUIRED ];
}


// The request message for Users.BatchGetUsers.
// Next available tag: 2
message BatchGetUsersRequest {
  // The name of the users to request. At most 100 may be requested.
  repeated string names = 1 [
      (google.api.resource_reference) = {type: "api.crbug.com/User"},
      (google.api.field_behavior) = REQUIRED ];
}


// The response message for Users.BatchGetUsers.
// Next available tag: 2
message BatchGetUsersResponse {
  // The users that were requested.
  repeated User users = 1;
}


// The request message for Users.UpdateUser.
// Next available tag: 3
message UpdateUserRequest {
  // The user's `name` field is used to identify the user to be updated.
  User user = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/User"} ];
  // The list of fields to be updated.
  google.protobuf.FieldMask update_mask = 2 [ (google.api.field_behavior) = REQUIRED ];
}


// The request message for Users.StarProject.
// Next available tag: 2
message StarProjectRequest {
  // The resource name for the Project to star.
  string project = 1 [
      (google.api.resource_reference) = {type: "api.crbug.com/Project"},
      (google.api.field_behavior) = REQUIRED ];
}


// The request message for Users.UnStarProject.
// Next available tag: 2
message UnStarProjectRequest {
  // The resource name for the Project to unstar.
  string project = 1 [
      (google.api.resource_reference) = {type: "api.crbug.com/Project"},
      (google.api.field_behavior) = REQUIRED ];
}


// The request message for Users.ListProjectStars.
// Next available tag: 4
message ListProjectStarsRequest {
  // The resource name for the user having stars listed.
  string parent = 1 [
      (google.api.resource_reference) = {type: "api.crbug.com/User"},
      (google.api.field_behavior) = REQUIRED ];
  // The maximum number of items to return. The service may return fewer than
  // this value.
  // If unspecified, at most 1000 items will be returned.
  int32 page_size = 2;
  // A page token, received from a previous `ListProjectStars` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListProjectStars` must
  // match the call that provided the page token.
  string page_token = 3;
}


// The response message for Users.ListProjectStars.
// Next available tag: 3
message ListProjectStarsResponse {
  // Data for each starred project.
  repeated ProjectStar project_stars = 1;
  // A token, which 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;
}