// Copyright 2025 Google LLC
//
// 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 google.cloud.run.v2;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/launch_stage.proto";
import "google/api/resource.proto";
import "google/api/routing.proto";
import "google/cloud/run/v2/condition.proto";
import "google/cloud/run/v2/instance_split.proto";
import "google/cloud/run/v2/vendor_settings.proto";
import "google/cloud/run/v2/worker_pool_revision_template.proto";
import "google/iam/v1/iam_policy.proto";
import "google/iam/v1/policy.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option go_package = "cloud.google.com/go/run/apiv2/runpb;runpb";
option java_multiple_files = true;
option java_outer_classname = "WorkerPoolProto";
option java_package = "com.google.cloud.run.v2";

// Cloud Run WorkerPool Control Plane API.
service WorkerPools {
  option (google.api.default_host) = "run.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Creates a new WorkerPool in a given project and location.
  rpc CreateWorkerPool(CreateWorkerPoolRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2/{parent=projects/*/locations/*}/workerPools"
      body: "worker_pool"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "parent"
        path_template: "projects/*/locations/{location=*}"
      }
    };
    option (google.api.method_signature) = "parent,worker_pool,worker_pool_id";
    option (google.longrunning.operation_info) = {
      response_type: "WorkerPool"
      metadata_type: "WorkerPool"
    };
  }

  // Gets information about a WorkerPool.
  rpc GetWorkerPool(GetWorkerPoolRequest) returns (WorkerPool) {
    option (google.api.http) = {
      get: "/v2/{name=projects/*/locations/*/workerPools/*}"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "name"
        path_template: "projects/*/locations/{location=*}/**"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Lists WorkerPools. Results are sorted by creation time, descending.
  rpc ListWorkerPools(ListWorkerPoolsRequest)
      returns (ListWorkerPoolsResponse) {
    option (google.api.http) = {
      get: "/v2/{parent=projects/*/locations/*}/workerPools"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "parent"
        path_template: "projects/*/locations/{location=*}"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Updates a WorkerPool.
  rpc UpdateWorkerPool(UpdateWorkerPoolRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      patch: "/v2/{worker_pool.name=projects/*/locations/*/workerPools/*}"
      body: "worker_pool"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "worker_pool.name"
        path_template: "projects/*/locations/{location=*}/**"
      }
    };
    option (google.api.method_signature) = "worker_pool";
    option (google.api.method_signature) = "worker_pool,update_mask";
    option (google.longrunning.operation_info) = {
      response_type: "WorkerPool"
      metadata_type: "WorkerPool"
    };
  }

  // Deletes a WorkerPool.
  rpc DeleteWorkerPool(DeleteWorkerPoolRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v2/{name=projects/*/locations/*/workerPools/*}"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "name"
        path_template: "projects/*/locations/{location=*}/**"
      }
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "WorkerPool"
      metadata_type: "WorkerPool"
    };
  }

  // Gets the IAM Access Control policy currently in effect for the given
  // Cloud Run WorkerPool. This result does not include any inherited policies.
  rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest)
      returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      get: "/v2/{resource=projects/*/locations/*/workerPools/*}:getIamPolicy"
    };
  }

  // Sets the IAM Access control policy for the specified WorkerPool. Overwrites
  // any existing policy.
  rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest)
      returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      post: "/v2/{resource=projects/*/locations/*/workerPools/*}:setIamPolicy"
      body: "*"
    };
  }

  // Returns permissions that a caller has on the specified Project.
  //
  // There are no permissions required for making this API call.
  rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest)
      returns (google.iam.v1.TestIamPermissionsResponse) {
    option (google.api.http) = {
      post: "/v2/{resource=projects/*/locations/*/workerPools/*}:testIamPermissions"
      body: "*"
    };
  }
}

// Request message for creating a WorkerPool.
message CreateWorkerPoolRequest {
  // Required. The location and project in which this worker pool should be
  // created. Format: `projects/{project}/locations/{location}`, where
  // `{project}` can be project id or number. Only lowercase characters, digits,
  // and hyphens.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "run.googleapis.com/WorkerPool"
    }
  ];

  // Required. The WorkerPool instance to create.
  WorkerPool worker_pool = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The unique identifier for the WorkerPool. It must begin with
  // letter, and cannot end with hyphen; must contain fewer than 50 characters.
  // The name of the worker pool becomes
  // `{parent}/workerPools/{worker_pool_id}`.
  string worker_pool_id = 3 [(google.api.field_behavior) = REQUIRED];

  // Optional. Indicates that the request should be validated and default values
  // populated, without persisting the request or creating any resources.
  bool validate_only = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for updating a worker pool.
message UpdateWorkerPoolRequest {
  // Optional. The list of fields to be updated.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Required. The WorkerPool to be updated.
  WorkerPool worker_pool = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Indicates that the request should be validated and default values
  // populated, without persisting the request or updating any resources.
  bool validate_only = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. If set to true, and if the WorkerPool does not exist, it will
  // create a new one. The caller must have 'run.workerpools.create' permissions
  // if this is set to true and the WorkerPool does not exist.
  bool allow_missing = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. If set to true, a new revision will be created from the template
  // even if the system doesn't detect any changes from the previously deployed
  // revision.
  //
  // This may be useful for cases where the underlying resources need to be
  // recreated or reinitialized. For example if the image is specified by label,
  // but the underlying image digest has changed) or if the container performs
  // deployment initialization work that needs to be performed again.
  bool force_new_revision = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for retrieving a list of WorkerPools.
message ListWorkerPoolsRequest {
  // Required. The location and project to list resources on.
  // Location must be a valid Google Cloud region, and cannot be the "-"
  // wildcard. Format: `projects/{project}/locations/{location}`, where
  // `{project}` can be project id or number.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "run.googleapis.com/WorkerPool"
    }
  ];

  // Maximum number of WorkerPools to return in this call.
  int32 page_size = 2;

  // A page token received from a previous call to ListWorkerPools.
  // All other parameters must match.
  string page_token = 3;

  // If true, returns deleted (but unexpired) resources along with active ones.
  bool show_deleted = 4;
}

// Response message containing a list of WorkerPools.
message ListWorkerPoolsResponse {
  // The resulting list of WorkerPools.
  repeated WorkerPool worker_pools = 1;

  // A token indicating there are more items than page_size. Use it in the next
  // ListWorkerPools request to continue.
  string next_page_token = 2;
}

// Request message for obtaining a WorkerPool by its full name.
message GetWorkerPoolRequest {
  // Required. The full name of the WorkerPool.
  // Format:
  // `projects/{project}/locations/{location}/workerPools/{worker_pool}`, where
  // `{project}` can be project id or number.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "run.googleapis.com/WorkerPool" }
  ];
}

// Request message to delete a WorkerPool by its full name.
message DeleteWorkerPoolRequest {
  // Required. The full name of the WorkerPool.
  // Format:
  // `projects/{project}/locations/{location}/workerPools/{worker_pool}`, where
  // `{project}` can be project id or number.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "run.googleapis.com/WorkerPool" }
  ];

  // Optional. Indicates that the request should be validated without actually
  // deleting any resources.
  bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL];

  // A system-generated fingerprint for this version of the
  // resource. May be used to detect modification conflict during updates.
  string etag = 3;
}

// WorkerPool acts as a top-level container that manages a set of
// configurations and revision templates which implement a pull-based workload.
// WorkerPool exists to provide a singular abstraction which can be access
// controlled, reasoned about, and which encapsulates software lifecycle
// decisions such as rollout policy and team resource ownership.
message WorkerPool {
  option (google.api.resource) = {
    type: "run.googleapis.com/WorkerPool"
    pattern: "projects/{project}/locations/{location}/workerPools/{worker_pool}"
    plural: "workerPools"
    singular: "workerPool"
    style: DECLARATIVE_FRIENDLY
  };

  // The fully qualified name of this WorkerPool. In CreateWorkerPoolRequest,
  // this field is ignored, and instead composed from
  // CreateWorkerPoolRequest.parent and CreateWorkerPoolRequest.worker_id.
  //
  // Format:
  // `projects/{project}/locations/{location}/workerPools/{worker_id}`
  string name = 1;

  // User-provided description of the WorkerPool. This field currently has a
  // 512-character limit.
  string description = 2;

  // Output only. Server assigned unique identifier for the trigger. The value
  // is a UUID4 string and guaranteed to remain unchanged until the resource is
  // deleted.
  string uid = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. A number that monotonically increases every time the user
  // modifies the desired state.
  // Please note that unlike v1, this is an int64 value. As with most Google
  // APIs, its JSON representation will be a `string` instead of an `integer`.
  int64 generation = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Unstructured key value map that can be used to organize and
  // categorize objects. User-provided labels are shared with Google's billing
  // system, so they can be used to filter, or break down billing charges by
  // team, component, environment, state, etc. For more information, visit
  // https://cloud.google.com/resource-manager/docs/creating-managing-labels or
  // https://cloud.google.com/run/docs/configuring/labels.
  //
  // Cloud Run API v2 does not support labels with  `run.googleapis.com`,
  // `cloud.googleapis.com`, `serving.knative.dev`, or `autoscaling.knative.dev`
  // namespaces, and they will be rejected. All system labels in v1 now have a
  // corresponding field in v2 WorkerPool.
  map<string, string> labels = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Unstructured key value map that may be set by external tools to
  // store and arbitrary metadata. They are not queryable and should be
  // preserved when modifying objects.
  //
  // Cloud Run API v2 does not support annotations with `run.googleapis.com`,
  // `cloud.googleapis.com`, `serving.knative.dev`, or `autoscaling.knative.dev`
  // namespaces, and they will be rejected in new resources. All system
  // annotations in v1 now have a corresponding field in v2 WorkerPool.
  //
  // <p>This field follows Kubernetes
  // annotations' namespacing, limits, and rules.
  map<string, string> annotations = 6 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The creation time.
  google.protobuf.Timestamp create_time = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The last-modified time.
  google.protobuf.Timestamp update_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The deletion time. It is only populated as a response to a
  // Delete request.
  google.protobuf.Timestamp delete_time = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. For a deleted resource, the time after which it will be
  // permamently deleted.
  google.protobuf.Timestamp expire_time = 10
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Email address of the authenticated creator.
  string creator = 11 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Email address of the last authenticated modifier.
  string last_modifier = 12 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Arbitrary identifier for the API client.
  string client = 13;

  // Arbitrary version identifier for the API client.
  string client_version = 14;

  // Optional. The launch stage as defined by [Google Cloud Platform
  //  Launch Stages](https://cloud.google.com/terms/launch-stages).
  //  Cloud Run supports `ALPHA`, `BETA`, and `GA`. If no value is specified, GA
  //  is assumed.
  //  Set the launch stage to a preview stage on input to allow use of preview
  //  features in that stage. On read (or output), describes whether the
  //  resource uses preview features.
  //
  //  For example, if ALPHA is provided as input, but only BETA and GA-level
  //  features are used, this field will be BETA on output.
  google.api.LaunchStage launch_stage = 16
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Settings for the Binary Authorization feature.
  BinaryAuthorization binary_authorization = 17
      [(google.api.field_behavior) = OPTIONAL];

  // Required. The template used to create revisions for this WorkerPool.
  WorkerPoolRevisionTemplate template = 18
      [(google.api.field_behavior) = REQUIRED];

  // Optional. Specifies how to distribute instances over a collection of
  // Revisions belonging to the WorkerPool. If instance split is empty or not
  // provided, defaults to 100% instances assigned to the latest `Ready`
  // Revision.
  repeated InstanceSplit instance_splits = 26
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies worker-pool-level scaling settings
  WorkerPoolScaling scaling = 20 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The generation of this WorkerPool currently serving traffic.
  // See comments in `reconciling` for additional information on reconciliation
  // process in Cloud Run. Please note that unlike v1, this is an int64 value.
  // As with most Google APIs, its JSON representation will be a `string`
  // instead of an `integer`.
  int64 observed_generation = 30 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The Condition of this WorkerPool, containing its readiness
  // status, and detailed error information in case it did not reach a serving
  // state. See comments in `reconciling` for additional information on
  // reconciliation process in Cloud Run.
  Condition terminal_condition = 31 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The Conditions of all other associated sub-resources. They
  // contain additional diagnostics information in case the WorkerPool does not
  // reach its Serving state. See comments in `reconciling` for additional
  // information on reconciliation process in Cloud Run.
  repeated Condition conditions = 32
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Name of the latest revision that is serving traffic. See
  // comments in `reconciling` for additional information on reconciliation
  // process in Cloud Run.
  string latest_ready_revision = 33 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = { type: "run.googleapis.com/Revision" }
  ];

  // Output only. Name of the last created revision. See comments in
  // `reconciling` for additional information on reconciliation process in Cloud
  // Run.
  string latest_created_revision = 34 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = { type: "run.googleapis.com/Revision" }
  ];

  // Output only. Detailed status information for corresponding instance splits.
  // See comments in `reconciling` for additional information on reconciliation
  // process in Cloud Run.
  repeated InstanceSplitStatus instance_split_statuses = 27
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // One or more custom audiences that you want this worker pool to support.
  // Specify each custom audience as the full URL in a string. The custom
  // audiences are encoded in the token and used to authenticate requests. For
  // more information, see
  // https://cloud.google.com/run/docs/configuring/custom-audiences.
  repeated string custom_audiences = 37;

  // Output only. Reserved for future use.
  bool satisfies_pzs = 38 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Returns true if the WorkerPool is currently being acted upon
  // by the system to bring it into the desired state.
  //
  // When a new WorkerPool is created, or an existing one is updated, Cloud Run
  // will asynchronously perform all necessary steps to bring the WorkerPool to
  // the desired serving state. This process is called reconciliation. While
  // reconciliation is in process, `observed_generation`,
  // `latest_ready_revison`, `traffic_statuses`, and `uri` will have transient
  // values that might mismatch the intended state: Once reconciliation is over
  // (and this field is false), there are two possible outcomes: reconciliation
  // succeeded and the serving state matches the WorkerPool, or there was an
  // error, and reconciliation failed. This state can be found in
  // `terminal_condition.state`.
  //
  // If reconciliation succeeded, the following fields will match: `traffic` and
  // `traffic_statuses`, `observed_generation` and `generation`,
  // `latest_ready_revision` and `latest_created_revision`.
  //
  // If reconciliation failed, `traffic_statuses`, `observed_generation`, and
  // `latest_ready_revision` will have the state of the last serving revision,
  // or empty for newly created WorkerPools. Additional information on the
  // failure can be found in `terminal_condition` and `conditions`.
  bool reconciling = 98 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. A system-generated fingerprint for this version of the
  // resource. May be used to detect modification conflict during updates.
  string etag = 99 [(google.api.field_behavior) = OUTPUT_ONLY];
}