// Copyright 2026 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.saasplatform.saasservicemgmt.v1beta1;

import "google/api/field_behavior.proto";
import "google/api/field_info.proto";
import "google/api/resource.proto";
import "google/cloud/saasplatform/saasservicemgmt/v1beta1/common.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.SaasPlatform.SaasServiceMgmt.V1Beta1";
option go_package = "cloud.google.com/go/saasplatform/saasservicemgmt/apiv1beta1/saasservicemgmtpb;saasservicemgmtpb";
option java_multiple_files = true;
option java_outer_classname = "SaasRolloutsResourcesProto";
option java_package = "com.google.cloud.saasplatform.saasservicemgmt.v1beta1";
option php_namespace = "Google\\Cloud\\SaasPlatform\\SaasServiceMgmt\\V1beta1";
option ruby_package = "Google::Cloud::SaasPlatform::SaasServiceMgmt::V1beta1";

// RolloutAction indicates the action to be performed on the Rollout.
enum RolloutAction {
  // Unspecified action, will be treated as RUN by default.
  ROLLOUT_ACTION_UNSPECIFIED = 0;

  // Run the Rollout until it naturally reaches a terminal state.
  // A rollout requested to run will progress through all natural Rollout
  // States (such as RUNNING -> SUCCEEDED or RUNNING -> FAILED).
  // If retriable errors are encountered during the rollout, the rollout
  // will paused by default and can be resumed by re-requesting this RUN
  // action.
  ROLLOUT_ACTION_RUN = 1;

  // Pause the Rollout until it is resumed (i.e. RUN is requested).
  ROLLOUT_ACTION_PAUSE = 2;

  // Cancel the Rollout permanently.
  ROLLOUT_ACTION_CANCEL = 3;
}

// Represents a single rollout execution and its results
message Rollout {
  option (google.api.resource) = {
    type: "saasservicemgmt.googleapis.com/Rollout"
    pattern: "projects/{project}/locations/{location}/rollouts/{rollout_id}"
    plural: "rollouts"
    singular: "rollout"
  };

  // The current state of the rollout.
  enum RolloutState {
    // Unspecified state.
    ROLLOUT_STATE_UNSPECIFIED = 0;

    // Rollout is in progress.
    ROLLOUT_STATE_RUNNING = 1;

    // Rollout has been paused.
    ROLLOUT_STATE_PAUSED = 2;

    // Rollout completed successfully.
    ROLLOUT_STATE_SUCCEEDED = 3;

    // Rollout has failed.
    ROLLOUT_STATE_FAILED = 4;

    // Rollout has been canceled.
    ROLLOUT_STATE_CANCELLED = 5;

    // Rollout is waiting for some condition to be met before starting.
    ROLLOUT_STATE_WAITING = 6;

    // Rollout is being canceled.
    ROLLOUT_STATE_CANCELLING = 7;

    // Rollout is being resumed.
    ROLLOUT_STATE_RESUMING = 8;

    // Rollout is being paused.
    ROLLOUT_STATE_PAUSING = 9;
  }

  // Identifier. The resource name (full URI of the resource) following the
  // standard naming scheme:
  //
  //   "projects/{project}/locations/{location}/rollout/{rollout_id}"
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Optional. Immutable. Name of the Release that gets rolled out to target
  // Units. Required if no other type of release is specified.
  string release = 3 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = IMMUTABLE,
    (google.api.resource_reference) = {
      type: "saasservicemgmt.googleapis.com/Release"
    }
  ];

  // Optional. Output only. The time when the rollout started executing. Will be
  // empty if the rollout hasn't started yet.
  google.protobuf.Timestamp start_time = 7 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Optional. Output only. The time when the rollout finished execution
  // (regardless of  success, failure, or cancellation). Will be empty if the
  // rollout hasn't finished yet. Once set, the rollout is in terminal state and
  // all the results are final.
  google.protobuf.Timestamp end_time = 8 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Output only. Current state of the rollout.
  RolloutState state = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Human readable message indicating details about the last state
  // transition.
  string state_message = 11 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Output only. The time when the rollout transitioned into its
  // current state.
  google.protobuf.Timestamp state_transition_time = 12 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Optional. Output only. The root rollout that this rollout is stemming from.
  // The resource name (full URI of the resource) following the standard naming
  // scheme:
  //
  //   "projects/{project}/locations/{location}/rollouts/{rollout_id}"
  string root_rollout = 16 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = {
      type: "saasservicemgmt.googleapis.com/Rollout"
    }
  ];

  // Optional. Output only. The direct parent rollout that this rollout is
  // stemming from. The resource name (full URI of the resource) following the
  // standard naming scheme:
  //
  //   "projects/{project}/locations/{location}/rollouts/{rollout_id}"
  string parent_rollout = 17 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = {
      type: "saasservicemgmt.googleapis.com/Rollout"
    }
  ];

  // Optional. The strategy used for executing this Rollout.
  // This strategy will override whatever strategy is specified in the
  // RolloutKind. If not specified on creation, the
  // strategy from RolloutKind will be used.
  //
  // There are two supported values strategies which are used to control
  // - "Google.Cloud.Simple.AllAtOnce"
  // - "Google.Cloud.Simple.OneLocationAtATime"
  //
  // A rollout with one of these simple strategies will rollout across
  // all locations defined in the targeted UnitKind's Saas Locations.
  string rollout_orchestration_strategy = 19
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. CEL(https://github.com/google/cel-spec) formatted filter string
  // against Unit. The filter will be applied to determine the eligible unit
  // population. This filter can only reduce, but not expand the scope of the
  // rollout. If not provided, the unit_filter from the RolloutKind will be
  // used.
  string unit_filter = 21 [(google.api.field_behavior) = OPTIONAL];

  // Required. Immutable. Name of the RolloutKind this rollout is stemming from
  // and adhering to.
  string rollout_kind = 22 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE,
    (google.api.resource_reference) = {
      type: "saasservicemgmt.googleapis.com/RolloutKind"
    }
  ];

  // Optional. Output only. Details about the progress of the rollout.
  RolloutStats stats = 24 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = OPTIONAL
  ];

  // Optional. Requested change to the execution of this rollout.
  // Default RolloutControl.action is ROLLOUT_ACTION_RUN meaning
  // the rollout will be executed to completion while progressing through
  // all natural Rollout States (such as RUNNING -> SUCCEEDED or RUNNING ->
  // FAILED). Requests can only be made when the Rollout is in a non-terminal
  // state.
  RolloutControl control = 25 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Output only. Output only snapshot of the effective unit filter at
  // Rollout start time. Contains a CEL(https://github.com/google/cel-spec)
  // expression consisting of a conjunction of Rollout.unit_filter and
  // RolloutKind.unit_filter. This field captures the filter applied by the
  // Rollout to determine the Unit population. If the associated RolloutKind's
  // unit_filter is modified after the rollout is started, it will not be
  // updated here.
  string effective_unit_filter = 26 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Optional. The labels on the resource, which can be used for categorization.
  // similar to Kubernetes resource labels.
  map<string, string> labels = 10401 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Annotations is an unstructured key-value map stored with a
  // resource that may be set by external tools to store and retrieve arbitrary
  // metadata. They are not queryable and should be preserved when modifying
  // objects.
  //
  // More info: https://kubernetes.io/docs/user-guide/annotations
  map<string, string> annotations = 10402
      [(google.api.field_behavior) = OPTIONAL];

  // Output only. The unique identifier of the resource. UID is unique in the
  // time and space for this resource within the scope of the service. It is
  // typically generated by the server on successful creation of a resource
  // and must not be changed. UID is used to uniquely identify resources
  // with resource name reuses. This should be a UUID4.
  string uid = 10201 [
    (google.api.field_info).format = UUID4,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Output only. An opaque value that uniquely identifies a version or
  // generation of a resource. It can be used to confirm that the client
  // and server agree on the ordering of a resource being written.
  string etag = 10202 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The timestamp when the resource was created.
  google.protobuf.Timestamp create_time = 10303
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The timestamp when the resource was last updated. Any
  // change to the resource made by users must refresh this value.
  // Changes to a resource made by the service should refresh this value.
  google.protobuf.Timestamp update_time = 10304
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The timestamp when the resource was marked for deletion
  // (deletion is an asynchronous operation).
  google.protobuf.Timestamp delete_time = 10305
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// An object that describes various settings of Rollout execution. Includes
// built-in policies across GCP and GDC, and customizable policies.
message RolloutKind {
  option (google.api.resource) = {
    type: "saasservicemgmt.googleapis.com/RolloutKind"
    pattern: "projects/{project}/locations/{location}/rolloutKinds/{rollout_kind_id}"
    plural: "rolloutKinds"
    singular: "rolloutKind"
  };

  enum UpdateUnitKindStrategy {
    // Strategy unspecified.
    UPDATE_UNIT_KIND_STRATEGY_UNSPECIFIED = 0;

    // Update the unit kind strategy on the rollout start.
    UPDATE_UNIT_KIND_STRATEGY_ON_START = 1;

    // Never update the unit kind.
    UPDATE_UNIT_KIND_STRATEGY_NEVER = 2;
  }

  // Identifier. The resource name (full URI of the resource) following the
  // standard naming scheme:
  //
  //   "projects/{project}/locations/{location}/rolloutKinds/{rollout_kind_id}"
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Required. Immutable. UnitKind that this rollout kind corresponds to.
  // Rollouts stemming from this rollout kind will target the units of this unit
  // kind. In other words, this defines the population of target units to be
  // upgraded by rollouts.
  string unit_kind = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE,
    (google.api.resource_reference) = {
      type: "saasservicemgmt.googleapis.com/UnitKind"
    }
  ];

  // Optional. The strategy used for executing a Rollout. This is a required
  // field.
  //
  // There are two supported values strategies which are used to control
  // - "Google.Cloud.Simple.AllAtOnce"
  // - "Google.Cloud.Simple.OneLocationAtATime"
  //
  // A rollout with one of these simple strategies will rollout across
  // all locations defined in the associated UnitKind's Saas Locations.
  string rollout_orchestration_strategy = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. CEL(https://github.com/google/cel-spec) formatted filter string
  // against Unit. The filter will be applied to determine the eligible unit
  // population. This filter can only reduce, but not expand the scope of the
  // rollout.
  string unit_filter = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The config for updating the unit kind. By default, the unit kind
  // will be updated on the rollout start.
  UpdateUnitKindStrategy update_unit_kind_strategy = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The configuration for error budget. If the number of failed units
  // exceeds max(allowed_count, allowed_ratio * total_units), the rollout will
  // be paused. If not set, all units will be attempted to be updated regardless
  // of the number of failures encountered.
  optional ErrorBudget error_budget = 7
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The labels on the resource, which can be used for categorization.
  // similar to Kubernetes resource labels.
  map<string, string> labels = 10401 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Annotations is an unstructured key-value map stored with a
  // resource that may be set by external tools to store and retrieve arbitrary
  // metadata. They are not queryable and should be preserved when modifying
  // objects.
  //
  // More info: https://kubernetes.io/docs/user-guide/annotations
  map<string, string> annotations = 10402
      [(google.api.field_behavior) = OPTIONAL];

  // Output only. The unique identifier of the resource. UID is unique in the
  // time and space for this resource within the scope of the service. It is
  // typically generated by the server on successful creation of a resource
  // and must not be changed. UID is used to uniquely identify resources
  // with resource name reuses. This should be a UUID4.
  string uid = 10201 [
    (google.api.field_info).format = UUID4,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Output only. An opaque value that uniquely identifies a version or
  // generation of a resource. It can be used to confirm that the client
  // and server agree on the ordering of a resource being written.
  string etag = 10202 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The timestamp when the resource was created.
  google.protobuf.Timestamp create_time = 10303
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The timestamp when the resource was last updated. Any
  // change to the resource made by users must refresh this value.
  // Changes to a resource made by the service should refresh this value.
  google.protobuf.Timestamp update_time = 10304
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The configuration for error budget. If the number of failed units exceeds
// max(allowed_count, allowed_ratio * total_units), the rollout will be paused.
message ErrorBudget {
  // Optional. The maximum number of failed units allowed in a location without
  // pausing the rollout.
  optional int32 allowed_count = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The maximum percentage of units allowed to fail (0, 100] within a
  // location without pausing the rollout.
  optional int32 allowed_percentage = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// RolloutStats contains information about the progress of a rollout.
message RolloutStats {
  // Optional. Output only. Unordered list. A breakdown of the progress of
  // operations triggered by the rollout. Provides a count of Operations by
  // their state. This can be used to determine the number of units which have
  // been updated, or are scheduled to be updated.
  //
  // There will be at most one entry per group.
  // Possible values for operation groups are:
  // - "SCHEDULED"
  // - "PENDING"
  // - "RUNNING"
  // - "SUCCEEDED"
  // - "FAILED"
  // - "CANCELLED"
  repeated Aggregate operations_by_state = 2 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = UNORDERED_LIST
  ];

  // Optional. Output only. Estimated number of units based. The estimation is
  // computed upon creation of the rollout.
  optional int64 estimated_total_unit_count = 3 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = OPTIONAL
  ];
}

// RolloutControl provides a way to request a change to the execution of a
// Rollout by pausing or canceling it.
message RolloutControl {
  // Parameters for the RUN action controlling the behavior of the rollout
  // when it is resumed from a PAUSED state.
  message RunRolloutActionParams {
    // Required. If true, the rollout will retry failed operations when resumed.
    // This is applicable only the current state of the Rollout is PAUSED and
    // the requested action is RUN.
    bool retry_failed_operations = 1 [(google.api.field_behavior) = REQUIRED];
  }

  // Setting for the action. The setting must match the action
  // e.g.: action=RUN may only set run_params or omit all parameters.
  // It is an error to set a setting that is not applicable to the action.
  oneof action_params {
    // Optional. Parameters for the RUN action. It is an error to specify this
    // if the RolloutAction is not set to RUN. By default, the rollout will
    // retry failed operations when resumed.
    RunRolloutActionParams run_params = 2
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Required. Action to be performed on the Rollout.
  // The default behavior is to run the rollout until it naturally reaches a
  // terminal state.
  RolloutAction action = 1 [(google.api.field_behavior) = REQUIRED];
}